Software Architecture Description

Revision History

1. Purpose

This document describes the software architecture of the foxBMS 2 POSIX port, satisfying ASPICE SWE.2 base practices. It defines the static structure (modules and their dependencies), the dynamic behavior (task scheduling and data flow), and the interfaces between software components.

2. Scope

The architecture encompasses 170+ source files organized into four layers, compiled for x86-64 with GCC 13.

3. References

4. Static Architecture

4.1 Module Dependency Diagram

                        +-------------------+
                        |    main.c         |
                        | (POSIX entry)     |
                        +--------+----------+
                                 |
                        +--------v----------+
                        |    sys.c          |
                        | SYS State Machine |
                        +--------+----------+
                                 |
              +------------------+------------------+
              |                  |                  |
     +--------v------+  +-------v-------+  +-------v--------+
     |   bms.c       |  |  database.c   |  |   diag.c       |
     | BMS State     |  | Data Store    |  | Diagnostic     |
     | Machine       |  |               |  | Handler        |
     +-------+-------+  +-------+-------+  +-------+--------+
             |                  ^                  ^
             |                  |                  |
     +-------v-------+         |                  |
     | contactor.c   |  +------+-------+   +------+-------+
     | Contactor     |  |   soa.c      |   | plausibility |
     | Driver        |  | Safe Op Area |   |    .c        |
     +-------+-------+  +------+-------+   +--------------+
             |                  |
     +-------v-------+  +------v-------+
     |   sps.c       |  | algorithm.c  |
     | Smart Power   |  | SOC/SOE/SOH  |
     | Switch        |  +--------------+
     +-------+-------+
             |                  +---------------+
     +-------v-------+         |  balancing.c  |
     |   HAL / POSIX |         |               |
     |   stubs       |         +---------------+
     +---------------+

     +---------------+  +---------------+  +---------------+
     |   can.c       |  |   spi.c       |  |   i2c.c       |
     | CAN Driver    |  | SPI Driver    |  | I2C Driver    |
     +-------+-------+  +-------+-------+  +-------+-------+
             |                  |                  |
     +-------v-------+  +------v--------+  +------v--------+
     | SocketCAN     |  | POSIX SPI     |  | POSIX I2C     |
     | (Linux)       |  | stub          |  | stub          |
     +---------------+  +---------------+  +---------------+

4.2 Module Catalog

4.3 Design Rules

1. No upward dependencies: Lower layers shall not depend on upper layers.
2. Single writer: Each database entry has exactly one writing module.
3. No direct hardware access: Application and Engine layers access hardware only through the Driver layer.
4. Uniform diagnostic reporting: All modules report faults through DIAG_Handler(), never through direct state manipulation.

5. Dynamic Architecture

5.1 Task Execution Sequence (POSIX)

Time -->

|-- 1ms tick --|-- 1ms tick --|-- 1ms tick --|-- ...

 ENGINE  1ms  AFE  10ms  100ms  I2C  ALGO
   |      |    |    |      |     |    |
   v      v    v    v      v     v    v
  [E1]  [T1] [A1]  .      .     .    .      <-- tick 0
  [E2]  [T2] [A2]  .      .     .    .      <-- tick 1
  ...   ...  ...   ...    ...   ...  ...
  [E10] [T10][A10][T10m]  .     .    .      <-- tick 9 (10ms fires)
  ...   ...  ...   ...    ...   ...  ...
  [E100][T100][A100][T10m][T100m][I1][AL1]  <-- tick 99 (100ms fires)

5.2 Interrupt-Free Model

The POSIX port has no hardware interrupts. All processing is synchronous within the cooperative loop. This simplifies concurrency analysis: there are no race conditions or priority inversions to consider.

5.3 Data Flow: Measurement to Safety Action

5.4 Data Flow: State Request to Contactor Actuation

6. Interface Definitions

6.1 Database API

/* Write a database entry (single-writer only) */
STD_RETURN_TYPE_e DATA_Write_1_DataBlock(DATA_BLOCK_HEADER_s *pDataBlockHeader);

/* Read a database entry (any module may read) */
STD_RETURN_TYPE_e DATA_Read_1_DataBlock(DATA_BLOCK_HEADER_s *pDataBlockHeader);

6.2 DIAG API

/* Report a diagnostic event */
STD_RETURN_TYPE_e DIAG_Handler(
    DIAG_ID_e       diagId,
    DIAG_EVENT_e    event,       /* DIAG_EVENT_OK or DIAG_EVENT_NOT_OK */
    DIAG_IMPACT_e   impact,
    uint32_t        data
);

/* Check if any FATAL flag is set */
bool DIAG_IsAnyFatalErrorSet(void);

6.3 BMS API

/* Get current BMS state */
BMS_STATE_e BMS_GetState(void);

/* BMS state machine trigger (called from 100ms task) */
void BMS_Trigger(void);

6.4 Contactor API

/* Request contactor state */
STD_RETURN_TYPE_e CONT_SetContactorState(
    CONT_NAMES_e    contactor,
    CONT_STATE_e    requestedState
);

/* Get contactor feedback */
CONT_STATE_e CONT_GetContactorFeedback(CONT_NAMES_e contactor);

6.5 CAN API (POSIX SocketCAN)

/* Initialize SocketCAN interface */
STD_RETURN_TYPE_e CAN_Initialize(const char *interface);  /* e.g., "vcan0" */

/* Transmit a CAN frame */
STD_RETURN_TYPE_e CAN_Send(uint32_t id, const uint8_t *data, uint8_t dlc);

/* Receive a CAN frame (non-blocking) */
STD_RETURN_TYPE_e CAN_Receive(uint32_t *id, uint8_t *data, uint8_t *dlc);

7. Resource Budgets (POSIX Target)

8. Design Decisions

End of Document