Diagnostic Log and Trace (DLT)

Синхронная и нереентерабельная функция Dlt_Init (идентификатор сервиса 0x01, доступна через заголовочный файл Dlt.h) инициализирует модуль Diagnostic Log and Trace (DLT) на платформе Classic [SWS_Dlt_00239]. Через параметр config она принимает указатель на структуру конфигурации конкретного модуля типа Dlt_ConfigType и не возвращает никакого значения [SWS_Dlt_00239].

Для контекста вызова и временного взаимодействия с другими BSW-модулями действуют специфические граничные условия:

• Порядок инициализации: модуль DLT использует NVRam Manager и должен инициализироваться на очень позднем этапе запуска электронного блока управления [SWS_Dlt_00239]. Вызов функции Dlt_Init должен обязательно происходить только после полной инициализации NVRam Manager [SWS_Dlt_00239].
• Энергонезависимые данные: если параметр конфигурации DltGeneralNvRAMSupport установлен в TRUE, модуль DLT в Dlt_Init использует интерфейс NvM_ReadBlock менеджера NVRAM для восстановления постоянных значений необходимых переменных [SWS_Dlt_00453].
• Обработка буфера: как только модуль инициализирован с помощью Dlt_Init и истек опциональный таймер DltGeneralStartUpDelayTimer, все буферизованные к этому моменту данные Log and Trace обрабатываются и отправляются в соответствии со спецификацией [SWS_Dlt_00005].

Поскольку функция специфицирована как нереентерабельная, вызывающий контекст должен гарантировать, что повторный вход в Dlt_Init во время выполнения параллельно или с прерыванием не происходит [SWS_Dlt_00239].

Синхронная и реэнтрантная функция Dlt_SendTraceMessage служит модулям базового программного обеспечения (BSW), а также программным компонентам (SW-C) для передачи параметров трассировки в модуль Dlt [SWS_Dlt_00243].

Параметры и контекст вызова

При вызове через sessionId передаются идентификатор модуля или порта, через traceInfo — метаданные для фильтрации сообщений, а через traceData — буфер полезных данных вместе с указанием длины traceDataLength [SWS_Dlt_00243]. Модуль может буферизовать сообщения трассировки даже в том случае, если Dlt ещё не был инициализирован [SWS_Dlt_00003].

Возвращаемые значения и обработка ошибок

Служба сигнализирует о статусе через специфические возвращаемые значения [SWS_Dlt_00243]:

• E_OK: операция успешно выполнена.
• DLT_E_MSG_TOO_LARGE: сообщение превышает допустимый размер всех назначенных каналов журналирования.
• DLT_E_NO_BUFFER: недостаточно памяти буфера; сообщение не может быть сохранено в промежуточный буфер хотя бы для одного канала журналирования.
• DLT_E_UNKNOWN_SESSION_ID: переданный sessionId неизвестен модулю.

Взаимодействие с hook-функциями

Поскольку Dlt_SendTraceMessage специфицирована как интерфейс для SW-C, для сгенерированных hook-функций существует эквивалентная внутренняя реализация [SWS_Dlt_00285], которая отправляет сообщения трассировки в режиме non-verbose [SWS_Dlt_00277].

Синхронная и реэнтрантная функция Dlt_SendLogMessage (идентификатор службы 0x03) служит модулям базового программного обеспечения (BSW), а также программным компонентам (SW-C) в качестве стандартизированного интерфейса для отправки сообщений журнала [SWS_Dlt_00241]. Вызов осуществляется через заголовочный файл Dlt.h, и благодаря реэнтрантности функция рассчитана на параллельное использование [SWS_Dlt_00241].

При вызове функции требуются четыре входных параметра, тогда как выходные параметры не используются [SWS_Dlt_00241]:

• sessionId: представляет идентификатор сессии. Для SW-C этот параметр невидим в качестве значения аргумента, связанного с портом, тогда как модули BSW напрямую передают свой номер модуля.
• logInfo: указатель на константную структуру, содержащую релевантные метаданные для фильтрации сообщения журнала.
• logData: указатель на массив байтов с регистрируемыми данными, образующий фактическую полезную нагрузку (payload) сообщения.
• logDataLength: числовая длина буфера данных logData.

Обработка ошибок выполняется непосредственно через возвращаемое значение типа Std_ReturnType, которое указывает на успешность операции или специфические состояния ошибок [SWS_Dlt_00241]:

• DLT_OK: сообщение журнала успешно принято и обработано.
• DLT_E_MSG_TOO_LARGE: сообщение превышает максимально допустимый размер буфера для всех назначенных каналов журналирования.
• DLT_E_NO_BUFFER: сообщение не удалось поместить в промежуточный буфер ни на одном из назначенных каналов журналирования.
• DLT_E_UNKNOWN_SESSION_ID: переданный идентификатор сессии недействителен или неизвестен модулю.

Использование

Синхронная функция Dlt_UnregisterContext (идентификатор службы 0x16) предоставляется через заголовочный файл Dlt.h и должна вызываться при останове программного модуля [SWS_Dlt_00769]. Она служит для отмены регистрации ранее зарегистрированного контекста приложения.

Функция ожидает три входных параметра [SWS_Dlt_00769]:

• sessionId: номер модуля; соответствует идентификатору модуля (Modul-ID) внутри BSW или заданному для конкретного порта значению аргумента внутри программного компонента (SW-C) [SWS_Dlt_00769].
• appId: идентификатор вышестоящего приложения (Application ID) [SWS_Dlt_00769].
• contextId: идентификатор контекста, регистрация которого отменяется (Context ID) [SWS_Dlt_00769].

Возвращаемые значения и обработка ошибок

Возвращаемое значение типа Std_ReturnType предоставляет информацию о результате выполнения [SWS_Dlt_00769]:

• E_OK: запрошенная операция успешно завершена [SWS_Dlt_00769].
• DLT_E_CONTEXT_NOT_YET_REG: контекст программного модуля предварительно не был зарегистрирован [SWS_Dlt_00769].
• DLT_E_UNKNOWN_SESSION_ID: переданный идентификатор сессии (Session-ID) неизвестен [SWS_Dlt_00769].

Параллелизм и ограничения

Функция специфицирована как реентрабельная и ведет себя синхронно [SWS_Dlt_00769]. Вызывающие модули должны убедиться, что переданный идентификатор сессии действителен и контекст перед завершением действительно был зарегистрирован, чтобы избежать ошибок при дерегистрации [SWS_Dlt_00769].

Использование и контекст вызова

Синхронный интерфейс Dlt_DetForwardErrorTrace с Service-ID 0x07 служит для перенаправления зарегистрированных ошибок разработки из Default Error Tracer (DET) в модуль Dlt [SWS_Dlt_00432]. Модуль Dlt предоставляет этот сервис для обеспечения требуемой возможности разветвления (Fan-Out) сообщений об ошибках DET [SWS_Dlt_00430]. Объявление этой C-функции подключено через заголовочный файл Dlt_Det.h [SWS_Dlt_00432].

Параметры и спецификация интерфейса

Функция принимает четыре обязательных входных параметра и не определяет ни возвращаемых значений, ни выходных параметров [SWS_Dlt_00432]:

• moduleId: ID вызывающего программного модуля, в котором произошла ошибка.
• instanceId: идентификатор индексного экземпляра модуля (нумерация начинается с 0; модули с одиночным экземпляром передают 0).
• apiId: идентификатор затронутого сервиса API (определен в спецификации вызывающего модуля).
• errorId: идентификатор обнаруженной ошибки разработки (определен в спецификации вызывающего модуля).

Параллелизм и обработка ошибок

Выполнение происходит синхронно с вызывающей регистрацией ошибок. Являясь неревходабельной функцией (Non Reentrant), интерфейс строго требует предотвращения конкурирующего выполнения на стороне вызывающего объекта [SWS_Dlt_00432]. Специфические коды ошибок, обратная связь по ошибкам или отдельные сообщения DET либо DEM для этого сервиса в спецификации не предусмотрены [SWS_Dlt_00432].

Синхронная функция Dlt_SetTraceStatus служит для установки статуса трассировки для определенного кортежа из Application-ID и Context-ID [SWS_Dlt_00254]. Она определена в заголовочном файле Dlt.h и имеет Service-ID 0x09 [SWS_Dlt_00254].

Использование

Для вызова требуются три входных параметра [SWS_Dlt_00254]:

• appId: ID программного компонента (тип Dlt_ApplicationIDType).
• contextId: ID контекста (тип Dlt_ContextIDType).
• newTraceStatus: вновь устанавливаемый статус трассировки как логическое значение (тип boolean).

Обработка ошибок и возвращаемые значения

Функция синхронно возвращает статус типа Std_ReturnType [SWS_Dlt_00254]:

• E_OK: ошибка не возникла, и статус был успешно применен.
• E_NOT_OK: статус трассировки изменить не удалось. Специфические сообщения об ошибках DET в спецификации функции не указаны (интерпретация: ошибка, вероятно, имеет место при недопустимых идентификаторах или некорректном состоянии модуля). Вопрос Q-77e190707462c8f1 (открытый)

Параллелизм и ограничения

Интерфейс специфицирован как нереентерабельный (Non Reentrant) [SWS_Dlt_00254]. Поэтому он не должен выполняться параллельно или с прерыванием без надлежащей синхронизации со стороны вызывающей стороны.

Использование

Функция Dlt_StoreConfiguration ([SWS_Dlt_00736]) служит для сохранения текущей конфигурации Dlt в энергонезависимую память (NVRAM). Сохранение выполняется внутренне через синхронный вызов интерфейса NvM_WriteBlock() менеджера NVRAM ([SWS_Dlt_00736]). API предоставляется через заголовочный файл Dlt.h с Service-ID 0x1a.

Функция имеет сигнатуру Std_ReturnType Dlt_StoreConfiguration(void) и не обрабатывает ни входные, ни выходные, ни входные/выходные параметры ([SWS_Dlt_00736]).

Обработка ошибок и возвращаемые значения

Будучи синхронной службой, функция непосредственно возвращает вызывающей стороне код состояния типа Std_ReturnType ([SWS_Dlt_00736]):

• E_OK: конфигурация безошибочно передана в NVRAM ([SWS_Dlt_00736]).
• E_NOT_OK: при сохранении конфигурации Dlt произошла ошибка ([SWS_Dlt_00736]).
• DLT_E_NOT_SUPPORTED: служба сохранения конфигурации не поддерживается модулем ([SWS_Dlt_00736]).

Параллелизм и ограничения

Согласно [SWS_Dlt_00736], Dlt_StoreConfiguration специфицирована как нереентерабельная (Non Reentrant). Поэтому функция не должна выполняться параллельно из различных задач или контекстов, так что на стороне вызывающего объекта необходимо обеспечить последовательное выполнение.

Использование

Синхронная функция Dlt_ResetToFactoryDefault предоставляется через заголовочный файл Dlt.h и не принимает входных параметров [SWS_Dlt_00739]. Ее основное назначение — сброс конфигурации времени выполнения Dlt: она сбрасывает уровень логирования и статус трассировки на постоянно сохраненные значения по умолчанию [SWS_Dlt_00739]. Если в модуле Dlt дополнительно активирована поддержка NVRAM, вызов приводит к полному удалению всех значений Dlt, сохраненных в NvM [SWS_Dlt_00739].

Возвращаемые значения и обработка ошибок

Результат операции синхронно сигнализируется через возвращаемое значение типа Std_ReturnType [SWS_Dlt_00739]:

• E_OK: конфигурация успешно сброшена на значения по умолчанию [SWS_Dlt_00739].
• E_NOT_OK: сброс конфигурации завершился сбоем [SWS_Dlt_00739].

Специфические сообщения об ошибках DET или DEM для этой службы в рамках данной спецификации не определены.

Параллелизм и ограничения

Функция специфицирована как нереентерабельная (Non Reentrant) (Service-ID 0x06) [SWS_Dlt_00739]. Параллельный или прерывающий вызов из различных задач или контекстов поэтому недопустим и должен предотвращаться вызывающей стороной.

Функция Dlt_RxIndication служит для индикации принятого PDU из нижележащего модуля коммуникационного интерфейса в модуль DLT [SWS_Dlt_00272]. Она доступна через заголовочный файл Dlt.h и имеет Service-ID 0x42 [SWS_Dlt_00272].

Вызов выполняется с синхронной семантикой и не имеет возвращаемого значения (void) [SWS_Dlt_00272]. В функцию передаются два входных параметра:

• RxPduId: идентификатор принятого PDU (типа PduIdType) [SWS_Dlt_00272].
• PduInfoPtr: указатель на структуру типа PduInfoType. Она содержит длину принятого PDU (SduLength), указатель на буфер с полезными данными PDU (SduDataPtr), а также соответствующие метаданные PDU [SWS_Dlt_00272].

Что касается параллелизма и контекста выполнения, функция является ревходабельной для различных PDU-ID, однако неревходабельна для одного и того же PDU-ID [SWS_Dlt_00272]. Следовательно, вызывающий нижележащий модуль не должен допускать параллельной обработки одного и того же RxPduId, тогда как параллельные вызовы с различными PDU-ID разрешены [SWS_Dlt_00272].

Синхронная функция Dlt_TriggerTransmit служит согласно [SWS_Dlt_00754] для копирования данных SDU по запросу нижележащего уровня в предоставленный буфер. Она объявлена в Dlt.h и имеет идентификатор службы 0x41.

При вызове передаются следующие параметры:

• TxPduId: идентификатор SDU, передача которой запрашивается.
• PduInfoPtr: указатель на структуру типа PduInfoType. Вызывающая сторона передает через SduDataPtr целевой буфер, а через SduLength — максимально доступный размер буфера.

Внутри функции модуль согласно [SWS_Dlt_00754] проверяет, помещаются ли доступные данные в переданный размер буфера:

• Если данные помещаются, функция копирует полезные данные в SduDataPtr, обновляет SduLength количеством фактически скопированных байтов и возвращает E_OK.
• Если буфера недостаточно, функция возвращает E_NOT_OK без модификации PduInfoPtr.

Если возвращается E_NOT_OK, данные SDU скопированы не были. Вызывающая сторона в этом случае не должна далее использовать PduInfoPtr, так как он может указывать на недействительные данные или являться указателем NULL [SWS_Dlt_00754].

С точки зрения параллелизма функция Dlt_TriggerTransmit реентрабельна для различных идентификаторов PDU (PDU-ID), но не реентрабельна для одного и того же TxPduId [SWS_Dlt_00754].

Использование и контекст вызова

Функция Dlt_TxConfirmation служит интерфейсом подтверждения нижележащего уровня коммуникации (lower layer communication interface module) для модуля Diagnostic Log and Trace (DLT) [SWS_Dlt_00273]. Она синхронно информирует модуль DLT о том, была ли ранее запрошенная PDU успешно передана или же передача завершилась сбоем [SWS_Dlt_00273]. Функция имеет Service-ID 0x40 и предоставляется через заголовочный файл Dlt.h [SWS_Dlt_00273].

Интерфейс не имеет возвращаемого значения (void) и ожидает два входных параметра [SWS_Dlt_00273]:

• TxPduId: идентификатор переданной PDU типа PduIdType.
• result: статус передачи типа Std_ReturnType; при этом E_OK сигнализирует об успешной передаче, а E_NOT_OK — о сбое передачи PDU.

Обработка ошибок и параллелизм

Явная обработка ошибок с возвращаемыми значениями ошибок или специальными сообщениями DET либо DEM для этого вызова не специфицирована; о сбое процесса отправки модулю DLT сообщается исключительно через значение параметра result = E_NOT_OK [SWS_Dlt_00273].

Для выполнения действует дифференцированное условие реентерабельности: Dlt_TxConfirmation реентерабельна для различных PDU-ID, однако нереентерабельна для одного и того же PDU-ID [SWS_Dlt_00273]. Поэтому вызывающие драйверы или интерфейсы должны гарантировать исключение одновременных вызовов с идентичным TxPduId, тогда как подтверждения для различных PDU могут поступать параллельно.

Функция Dlt_TpTxConfirmation служит в качестве синхронной функции подтверждения модуля Dlt после отправки транспортной I-PDU [SWS_Dlt_00756]. Она доступна через заголовочный файл Dlt.h с идентификатором службы 0x48 [SWS_Dlt_00756].

Использование и семантика

Вызов выполняется после того, как I-PDU была передана по соответствующей сети [SWS_Dlt_00756]. Функция имеет сигнатуру void Dlt_TpTxConfirmation (PduIdType id, Std_ReturnType result) и не возвращает значения [SWS_Dlt_00756]:

• id (входной параметр, тип PduIdType): однозначная идентификация переданной I-PDU [SWS_Dlt_00756].
• result (входной параметр, тип Std_ReturnType): указывает статус передачи и показывает, была ли отправка I-PDU успешной или завершилась сбоем [SWS_Dlt_00756].

Параллелизм и обработка ошибок

Спецификация определяет Dlt_TpTxConfirmation как синхронную и реентрабельную (Reentrant) [SWS_Dlt_00756]. Специфические коды ошибок DET или DEM для этой службы не определены; обработка ошибок применительно к процессу отправки опирается на анализ параметра result [SWS_Dlt_00756]. В системном контексте вызов, как правило, инициируется нижележащим транспортным уровнем после завершения передачи PDU. Вопрос Q-0e5ab7c285316701 (открытый)

Использование и семантика

Синхронная и ревходабельная функция Dlt_CopyTxData служит для извлечения передаваемых данных сегмента I-PDU (N-PDU) из модуля Dlt [SWS_Dlt_00516]. Через id указывается передаваемый I-PDU, тогда как info предоставляет целевой буфер (SduDataPtr) и требуемую длину в байтах (SduLength) [SWS_Dlt_00516]. Передача SduLength = 0 (при которой SduDataPtr может быть передан как NULL_PTR) позволяет передавать чисто изменения статуса через retry или запрашивать оставшийся объем данных в буфере передачи [SWS_Dlt_00516]. Через выходной параметр availableDataPtr функция сообщает об оставшемся доступном объеме данных в Tx-буфере, что, например, позволяет TP-модулям с динамической длиной полезных данных (таким как FrIsoTp) определять размер последующих сегментов [SWS_Dlt_00516].

Подтверждение и устранение ошибок

Через указатель retry управляется квитирование или повторная передача [SWS_Dlt_00516]:

• Если retry является NULL_PTR, скопированные данные разрешается отбросить из буфера непосредственно после операции копирования [SWS_Dlt_00516].
• Если TpDataState указывает на значение TP_CONFPENDING, ранее скопированные данные должны оставаться в буфере для возможного устранения ошибок [SWS_Dlt_00516].
• При TP_DATACONF все переданные до вызова данные считаются подтвержденными и могут быть освобождены [SWS_Dlt_00516].
• При TP_DATARETRY модуль снова начинает копирование с байтового смещения, переданного в TxTpDataCnt [SWS_Dlt_00516].

Возвращаемые значения и граничные условия

Результат запроса сообщается как BufReq_ReturnType [SWS_Dlt_00516]:

• BUFREQ_OK: данные были полностью скопированы в целевой буфер в соответствии с запросом [SWS_Dlt_00516].
• BUFREQ_E_BUSY: запрашиваемый объем данных недоступен; данные не были скопированы, последующая повторная попытка разрешена [SWS_Dlt_00516].
• BUFREQ_E_NOT_OK: запрос завершился сбоем; данные не были скопированы [SWS_Dlt_00516].

Интерфейс доступен через Dlt.h и спроектирован как ревходабельный [SWS_Dlt_00516]. Контекст вызова, как правило, находится в нижележащем модуле транспортного протокола во время сегментированной передачи. Вопрос Q-a81c439e73e0acc0 (открытый)

Синхронная и реентрабельная функция Dlt_StartReception вызывается в начале приема N-SDU, которая может приниматься в виде одиночного кадра (SF) или фрагментированно через несколько N-PDU [SWS_Dlt_91006]. Она служит для инициализации транспортного соединения в модуле Dlt и предоставления доступного буфера приема [SWS_Dlt_91006].

Через параметр id идентифицируется принятая I-PDU, в то время как info передает полезные данные и метаданные первого кадра либо установлен в NULL_PTR, если отсутствуют как данные, так и метаданные [SWS_Dlt_91006]. Через TpSduLength передается общая длина N-SDU; если функция вызывается с длиной 0, она возвращает текущий максимально доступный размер буфера через bufferSizePtr [SWS_Dlt_91006]. Транспортный протокол использует значение из bufferSizePtr для вычисления размера блока (Block Size, BS) [SWS_Dlt_91006].

Если соединение принимается, функция возвращает BUFREQ_OK; если для запрошенного размера недостаточно буфера, bufferSizePtr сигнализирует о размере буфера 0 для продолжения приема [SWS_Dlt_91006]. При отклонении соединения BUFREQ_E_NOT_OK прерывает прием, а при недостатке общего объема памяти сообщается BUFREQ_E_OVFL; в обоих случаях ошибки bufferSizePtr остается без изменений [SWS_Dlt_91006].

Функция Dlt_TpRxIndication служит синхронной индикацией приема после того, как I-PDU была принята через TP-API [SWS_Dlt_91007]. Она объявлена в заголовочном файле Dlt.h и имеет идентификатор службы 0x45 [SWS_Dlt_91007].

Использование и параметры

Передача в модуль DLT осуществляется через два входных параметра, при этом функция не возвращает значения [SWS_Dlt_91007]:

• id (тип PduIdType): обозначает идентификацию принятой I-PDU [SWS_Dlt_91007].
• result (тип Std_ReturnType): указывает результат приема и показывает, была ли передача успешной [SWS_Dlt_91007].

Параллелизм и ограничения

Интерфейс определен как синхронный и реентрабельный [SWS_Dlt_91007]. Входных/выходных, а также чисто выходных параметров не существует [SWS_Dlt_91007].

Обработка ошибок и взаимодействие

Результат транспортировки сигнализируется модулю DLT исключительно через аргумент result; специфические коды ошибок, сообщения DET или DEM не специфицированы [SWS_Dlt_91007].

Интерпретация: вызов, по всей вероятности, осуществляется нижележащим компонентом транспортного протокола, как только сообщение DLT поступило полностью или передача прерывается [SWS_Dlt_91007]. Вопрос Q-7d9c8564a2404acf (открытый)

Использование и семантика

Синхронная функция Dlt_CopyRxData вызывается для передачи принятых данных сегмента I-PDU (N-PDU) на верхний уровень [SWS_Dlt_91008]. Каждый вызов предоставляет очередную часть данных I-PDU, при этом оставшийся размер буфера записывается по адресу памяти, на который ссылается bufferSizePtr [SWS_Dlt_91008]. Объявление доступно через заголовочный файл Dlt.h [SWS_Dlt_91008].

Параметры и запрос буфера

Через входной параметр id идентифицируется принятая I-PDU [SWS_Dlt_91008]. Указатель info предоставляет через SduDataPtr исходный буфер, а также через SduLength количество копируемых байтов [SWS_Dlt_91008]. Если SduLength передается со значением 0, вызов служит исключительно для запроса буфера, доступного в данный момент в верхнем модуле; в этом случае SduDataPtr может являться NULL_PTR [SWS_Dlt_91008]. Выходной параметр bufferSizePtr возвращает размер буфера приема, остающийся свободным после операции копирования [SWS_Dlt_91008].

Параллелизм и возвращаемые значения

Функция выполнена реентрабельной и имеет идентификатор службы 0x44 [SWS_Dlt_91008]. Возвращаемое значение типа BufReq_ReturnType сигнализирует о результате операции копирования: при успешном приеме данных служба возвращает BUFREQ_OK, тогда как в случае ошибки возвращается BUFREQ_E_NOT_OK [SWS_Dlt_91008].

Использование и контекст вызова

Функция Dlt_TxFunction согласно спецификации [SWS_Dlt_91005] определена как служба с идентификатором службы 0x80 и доступна через заголовочный файл SchM_Dlt.h. Ее сигнатура интерфейса имеет вид void Dlt_TxFunction (void) [SWS_Dlt_91005]. Объявление в SchM_Dlt.h в качестве интерпретации указывает на то, что вызов осуществляется планировщиком BSW в контексте циклической задачи (Task) и не должен вызываться напрямую программными компонентами приложения (Software-Components).

Параметры и возвращаемые значения

Согласно [SWS_Dlt_91005] функция не принимает входных параметров и не возвращает значения (void). Судя по имени, функция, по всей вероятности, отвечает за циклическую обработку и передачу ожидающих отправки сообщений Dlt. Вопрос (открытый) Поскольку возвращаемые значения не специфицированы, обработка ошибок, предположительно, осуществляется сугубо внутри модуля или состояния.

ограничения

Поскольку полезная нагрузка не содержит сведений о реентрабельности или специальных ошибках разработки, интервалы вызова и назначения задачам необходимо согласовывать через конфигурацию диспетчера расписания (Schedule Manager). Другие коды ошибок или записи DET в [SWS_Dlt_91005] не указаны.