1.. _IOC_virtualization_hld: 2 3IOC Virtualization High-Level Design 4#################################### 5 6 7.. author: Yuan Liu 8 9The I/O Controller (IOC) is an SoC bridge we can use to communicate 10with a Vehicle Bus in automotive applications, routing Vehicle Bus 11signals, such as those extracted from CAN messages, from the IOC to the 12SoC and back, as well as signals the SoC uses to control onboard 13peripherals. 14 15.. note:: 16 Intel NUC and UP2 platforms do not support IOC hardware, and as such, IOC 17 virtualization is not supported on these platforms. 18 19The main purpose of IOC virtualization is to transfer data between 20native Carrier Board Communication (CBC) char devices and a virtual 21UART. IOC virtualization is implemented as full virtualization so the 22User VM can directly reuse the native CBC driver. 23 24The IOC Mediator has several virtualization requirements, such as S3/S5 25wakeup reason emulation, CBC link frame packing/unpacking, signal 26passlist, and RTC configuration. 27 28IOC Mediator Design 29******************* 30 31Architecture Diagrams 32===================== 33 34IOC Introduction 35---------------- 36 37.. figure:: images/ioc-image12.png 38 :width: 600px 39 :align: center 40 :name: ioc-mediator-arch 41 42 IOC Mediator Architecture 43 44- Vehicle Bus communication involves a wide range of individual signals 45 to be used, varying from single GPIO signals on the IOC up to 46 complete automotive networks that connect many external ECUs. 47- IOC (I/O controller) is an SoC bridge to communicate with a Vehicle 48 Bus. It routes Vehicle Bus signals (extracted from CAN 49 messages for example) back and forth between the IOC and SoC. It also 50 controls the onboard peripherals from the SoC. 51- IOC is always turned on. The power supply of the SoC and its memory are 52 controlled by the IOC. IOC monitors some wakeup reason to control SoC 53 lifecycle-related features. 54- Some hardware signals are connected to the IOC, allowing the SoC to control 55 them. 56- Besides, there is one NVM (Non-Volatile Memory) that is connected to 57 IOC for storing persistent data. The IOC is in charge of accessing NVM 58 following the SoC's requirements. 59 60CBC Protocol Introduction 61------------------------- 62 63The Carrier Board Communication (CBC) protocol multiplexes and 64prioritizes communication from the available interface between the SoC 65and the IOC. 66 67The CBC protocol offers a layered approach, which allows it to run on 68different serial connections, such as SPI or UART. 69 70.. figure:: images/ioc-image14.png 71 :width: 900px 72 :align: center 73 :name: ioc-cbc-frame-def 74 75 IOC Native - CBC Frame Definition 76 77The CBC protocol is based on a four-layer system: 78 79- The **Physical Layer** is a serial interface with full 80 duplex capabilities. A hardware handshake is required. The required 81 bit rate depends on the peripherals connected, e.g., UART and SPI. 82- The **Link Layer** handles the length and payload verification. 83- The **Address Layer** is used to distinguish between the general data 84 transferred. It is placed in front of the underlying Service Layer 85 and contains Multiplexer (MUX) and Priority fields. 86- The **Service Layer** contains the payload data. 87 88Native Architecture 89------------------- 90 91In the native architecture, the IOC controller connects to UART 92hardware, and communicates with the CAN bus to access peripheral 93devices. ``cbc_attach`` is an application to enable the CBC ldisc 94function, which creates several CBC char devices. All userspace 95subsystems or services communicate with IOC firmware via the CBC char 96devices. 97 98.. figure:: images/ioc-image13.png 99 :width: 900px 100 :align: center 101 :name: ioc-software-arch 102 103 IOC Native - Software Architecture 104 105Virtualization Architecture 106--------------------------- 107 108In the virtualization architecture, the IOC Device Model (DM) is 109responsible for communication between the User VM and IOC firmware. The IOC 110DM communicates with several native CBC char devices and a PTY device. 111The native CBC char devices only include ``/dev/cbc-lifecycle``, 112``/dev/cbc-signals``, and ``/dev/cbc-raw0`` - ``/dev/cbc-raw11``. Others 113are not used by the IOC DM. IOC DM opens the ``/dev/ptmx`` device to 114create a pair of devices (primary and secondary), The IOC DM uses these 115devices to communicate with UART DM since UART DM needs a TTY capable 116device as its backend. 117 118.. figure:: images/ioc-image15.png 119 :width: 900px 120 :align: center 121 :name: ioc-virt-software-arch 122 123 IOC Virtualization - Software Architecture 124 125High-Level Design 126================= 127 128There are five parts in this high-level design: 129 130* Software data flow introduces data transfer in the IOC mediator 131* State transfer introduces IOC mediator work states 132* CBC protocol illustrates the CBC data packing/unpacking 133* Power management involves boot/resume/suspend/shutdown flows 134* Emulated CBC commands introduce some commands workflow 135 136IOC mediator has three threads to transfer data between User VM and Service VM. The 137core thread is responsible for data reception, and Tx and Rx threads are 138used for data transmission. Each of the transmission threads has one 139data queue as a buffer, so that the IOC mediator can read data from CBC 140char devices and UART DM immediately. 141 142.. figure:: images/ioc-image16.png 143 :width: 900px 144 :align: center 145 :name: ioc-med-sw-data-flow 146 147 IOC Mediator - Software Data Flow 148 149- For Tx direction, the data comes from IOC firmware. IOC mediator 150 receives service data from native CBC char devices such as 151 ``/dev/cbc-lifecycle``. If service data is CBC wakeup reason, some wakeup 152 reason bits will be masked. If service data is CBC signal, the data 153 will be dropped and will not be defined in the passlist. If service 154 data comes from a raw channel, the data will be passed forward. Before 155 transmitting to the virtual UART interface, all data needs to be 156 packed with an address header and link header. 157- For Rx direction, the data comes from the User VM. The IOC mediator receives link 158 data from the virtual UART interface. The data will be unpacked by Core 159 thread, and then forwarded to Rx queue, similar to how the Tx direction flow 160 is done except that the heartbeat and RTC are only used by the IOC 161 mediator and will not be transferred to IOC 162 firmware. 163- IOC mediator only cares about lifecycle, signal, and raw data. 164 Others, such as diagnosis, are not used by the IOC mediator. 165 166State Transfer 167-------------- 168 169IOC mediator has four states and five events for state transfer. 170 171.. figure:: images/ioc-image18.png 172 :width: 600px 173 :align: center 174 :name: ioc-state-transfer 175 176 IOC Mediator - State Transfer 177 178- **INIT state**: This state is the initialized state of the IOC mediator. 179 All CBC protocol packets are handled normally. In this state, the User VM 180 has not yet sent an active heartbeat. 181- **ACTIVE state**: Enter this state if an HB ACTIVE event is triggered, 182 indicating that the User VM state has been active and need to set the bit 183 23 (SoC bit) in the wakeup reason. 184- **SUSPENDING state**: Enter this state if a RAM REFRESH event or HB 185 INACTIVE event is triggered. The related event handler needs to mask 186 all wakeup reason bits except SoC bit and drop the queued CBC 187 protocol frames. 188- **SUSPENDED state**: Enter this state if a SHUTDOWN event is triggered to 189 close all native CBC char devices. The IOC mediator will be put to 190 sleep until a RESUME event is triggered to re-open the closed native 191 CBC char devices and transition to the INIT state. 192 193CBC Protocol 194------------ 195 196IOC mediator needs to pack/unpack the CBC link frame for IOC 197virtualization, as shown in the detailed flow below: 198 199.. figure:: images/ioc-image17.png 200 :width: 900px 201 :align: center 202 :name: ioc-cbc-frame-usage 203 204 IOC Native - CBC Frame Usage 205 206In the native architecture, the CBC link frame is unpacked by CBC 207driver. The usage services only get the service data from the CBC char 208devices. For data packing, CBC driver will compute the checksum and set 209priority for the frame, then send data to the UART driver. 210 211.. figure:: images/ioc-image20.png 212 :width: 900px 213 :align: center 214 :name: ioc-cbc-prot 215 216 IOC Virtualizaton - CBC Protocol Virtualization 217 218The difference between the native and virtualization architectures is 219that the IOC mediator needs to re-compute the checksum and reset 220priority. Priority is not supported by IOC firmware; the 221priority setting by the IOC mediator is based on the priority setting of 222the CBC driver. The Service VM and User VM use the same CBC driver. 223 224Power Management Virtualization 225------------------------------- 226 227In acrn-dm, the IOC power management architecture involves PM DM, IOC 228DM, and UART DM modules. PM DM is responsible for User VM power management, 229and IOC DM is responsible for heartbeat and wakeup reason flows for IOC 230firmware. The heartbeat flow is used to control IOC firmware power state 231and wakeup reason flow is used to indicate IOC power state to the OS. 232UART DM transfers all IOC data between the Service VM and User VM. These modules 233complete boot/suspend/resume/shutdown functions. 234 235Boot Flow 236+++++++++ 237 238.. figure:: images/ioc-image19.png 239 :width: 900px 240 :align: center 241 :name: ioc-virt-boot 242 243 IOC Virtualizaton - Boot Flow 244 245#. Press ignition button for booting. 246#. Service VM lifecycle service gets a "booting" wakeup reason. 247#. Service VM lifecycle service notifies wakeup reason to VM Manager, and VM 248 Manager starts VM. 249#. VM Manager sets the VM state to "start". 250#. IOC DM forwards the wakeup reason to User VM. 251#. PM DM starts User VM. 252#. User VM lifecycle gets a "booting" wakeup reason. 253 254Suspend & Shutdown Flow 255+++++++++++++++++++++++ 256 257.. figure:: images/ioc-image21.png 258 :width: 900px 259 :align: center 260 :name: ioc-suspend 261 262 IOC Virtualizaton - Suspend and Shutdown by Ignition 263 264#. Press ignition button to suspend or shutdown. 265#. Service VM lifecycle service gets a 0x800000 wakeup reason, then keeps 266 sending a shutdown delay heartbeat to IOC firmware, and notifies a 267 "stop" event to VM Manager. 268#. IOC DM forwards the wakeup reason to User VM lifecycle service. 269#. Service VM lifecycle service sends a "stop" event to VM Manager, and waits for 270 the stop response before timeout. 271#. User VM lifecycle service gets a 0x800000 wakeup reason and sends inactive 272 heartbeat with suspend or shutdown SUS_STAT to IOC DM. 273#. User VM lifecycle service gets a 0x000000 wakeup reason, then enters 274 suspend or shutdown kernel PM flow based on SUS_STAT. 275#. PM DM executes User VM suspend/shutdown request based on ACPI. 276#. VM Manager queries each VM state from PM DM. Suspend request maps 277 to a paused state and shutdown request maps to a stop state. 278#. VM Manager collects all VMs' state, and reports it to Service VM lifecycle 279 service. 280#. Service VM lifecycle sends inactive heartbeat to IOC firmware with 281 suspend/shutdown SUS_STAT, based on the Service VM's own lifecycle service 282 policy. 283 284Resume Flow 285+++++++++++ 286 287.. figure:: images/ioc-image22.png 288 :width: 900px 289 :align: center 290 :name: ioc-resume 291 292 IOC Virtualizaton - Resume Flow 293 294The resume reason contains both the ignition button and RTC, and has 295the same flow blocks. 296 297For ignition resume flow: 298 299#. Press ignition button to resume. 300#. Service VM lifecycle service gets an initial wakeup reason from the IOC 301 firmware. The wakeup reason is 0x000020, from which the ignition button 302 bit is set. It then sends active or initial heartbeat to IOC firmware. 303#. Service VM lifecycle forwards the wakeup reason and sends start event to VM 304 Manager. The VM Manager starts to resume VMs. 305#. IOC DM gets the wakeup reason from the VM Manager and forwards it to User VM 306 lifecycle service. 307#. VM Manager sets the VM state to starting for PM DM. 308#. PM DM resumes User VM. 309#. User VM lifecycle service gets wakeup reason 0x000020, and then sends an initial 310 or active heartbeat. The User VM gets wakeup reason 0x800020 after 311 resuming. 312 313For RTC resume flow 314 315#. RTC timer expires. 316#. Service VM lifecycle service gets initial wakeup reason from the IOC 317 firmware. The wakeup reason is 0x000200, from which RTC bit is set. 318 It then sends active or initial heartbeat to IOC firmware. 319#. Service VM lifecycle forwards the wakeup reason and sends start event to VM 320 Manager. VM Manager begins resuming VMs. 321#. IOC DM gets the wakeup reason from the VM Manager, and forwards it to 322 the User VM lifecycle service. 323#. VM Manager sets the VM state to starting for PM DM. 324#. PM DM resumes User VM. 325#. User VM lifecycle service gets the wakeup reason 0x000200, and sends 326 initial or active heartbeat. The User VM gets wakeup reason 0x800200 327 after resuming. 328 329System Control Data 330------------------- 331 332IOC mediator has several emulated CBC commands, including wakeup reason, 333heartbeat, and RTC. 334 335The wakeup reason, heartbeat, and RTC commands belong to the system 336control frames, which are used for startup or shutdown control. System 337control includes Wakeup Reasons, Heartbeat, Boot Selector, Suppress 338Heartbeat Check, and Set Wakeup Timer functions. Details are in this 339table: 340 341.. list-table:: System Control SVC Values 342 :header-rows: 1 343 344 * - System Control 345 - Value Name 346 - Description 347 - Data Direction 348 349 * - 1 350 - Wakeup Reasons 351 - Wakeup Reasons 352 - IOC to SoC 353 354 * - 2 355 - Heartbeat 356 - Heartbeat 357 - SoC to IOC 358 359 * - 3 360 - Boot Selector 361 - Boot Selector 362 - SoC to IOC 363 364 * - 4 365 - Suppress Heartbeat Check 366 - Suppress Heartbeat Check 367 - SoC to IOC 368 369 * - 5 370 - Set Wakeup Timer 371 - Set Wakeup Timer in AIOC firmware 372 - SoC to IOC 373 374- IOC mediator only supports wakeup reasons Heartbeat and Set Wakeup 375 Timer. 376- The Boot Selector command is used to configure which partition the 377 IOC has to use for normal and emergency boots. Additionally, the IOC 378 has to report to the SoC after the CBC communication has been 379 established successfully with which boot partition has been started 380 and for what reason. 381- The Suppress Heartbeat Check command is sent by the SoC in 382 preparation for maintenance tasks which requires the CBC Server to be 383 shut down for a certain period of time. It instructs the IOC not to 384 expect CBC heartbeat messages during the specified time. The IOC must 385 disable any watchdog on the CBC heartbeat messages during this period 386 of time. 387 388Wakeup Reason 389+++++++++++++ 390 391The wakeup reasons command contains a bitmask of all reasons that are 392keeping the SoC/IOC active. The SoC itself also has a wakeup 393reason, which allows the SoC to keep the IOC active. The wakeup reasons 394should be sent every 1000 ms by the IOC. 395 396Wakeup reason frame definition is as below: 397 398.. figure:: images/ioc-image24.png 399 :width: 900px 400 :align: center 401 :name: ioc-wakeup-reason 402 403 Wakeup Reason Frame Definition 404 405The wakeup reason bits are supported by sources shown here: 406 407.. list-table:: Wakeup Reason Bits 408 :header-rows: 1 409 410 * - Wakeup Reason 411 - Bit 412 - Source 413 414 * - wakeup_button 415 - 5 416 - Get from IOC firmware, forward to User VM 417 418 * - RTC wakeup 419 - 9 420 - Get from IOC firmware, forward to User VM 421 422 * - Car door wakeup 423 - 11 424 - Get from IOC firmware, forward to User VM 425 426 * - SoC wakeup 427 - 23 428 - Emulation (Depends on User VM's heartbeat message 429 430- CBC_WK_RSN_BTN (bit 5): Ignition button. 431- CBC_WK_RSN_RTC (bit 9): RTC timer. 432- CBC_WK_RSN_DOR (bit 11): Car door. 433- CBC_WK_RSN_SOC (bit 23): SoC active/inactive. 434 435.. figure:: images/ioc-image4.png 436 :width: 600px 437 :align: center 438 :name: ioc-wakeup-flow 439 440 IOC Mediator - Wakeup Reason Flow 441 442Bit 23 is for the SoC wakeup indicator and should not be forwarded 443directly because every VM has a different heartbeat status. 444 445Heartbeat 446+++++++++ 447 448The Heartbeat is used for SoC watchdog, indicating the SoC power 449reset behavior. Heartbeat needs to be sent every 1000 ms by 450the SoC. 451 452.. figure:: images/ioc-image5.png 453 :width: 900px 454 :align: center 455 :name: ioc-heartbeat 456 457 System Control - Heartbeat 458 459Heartbeat frame definition is shown here: 460 461.. figure:: images/ioc-image6.png 462 :width: 900px 463 :align: center 464 :name: ioc-heartbeat-frame 465 466 Heartbeat Frame Definition 467 468- Heartbeat active is repeatedly sent from SoC to IOC to signal that 469 the SoC is active and intends to stay active. The On SUS_STAT action 470 must be set to invalid. 471- Heartbeat inactive is sent once from SoC to IOC to signal that the 472 SoC is ready for power shutdown. The On SUS_STAT action must be set 473 to a required value. 474- Heartbeat delay is repeatedly sent from SoC to IOC to signal that the 475 SoC has received the shutdown request, but isn't ready for 476 shutdown yet (for example, a phone call or other time consuming 477 action is active). The On SUS_STAT action must be set to invalid. 478 479.. figure:: images/ioc-image7.png 480 :width: 600px 481 :align: center 482 :name: ioc-heartbeat-commands 483 484 Heartbeat Commands 485 486- SUS_STAT invalid action needs to be set with a heartbeat active 487 message. 488- For the heartbeat inactive message, the SoC needs to be set from 489 command 1 to 7 following the related scenarios. For example: S3 case 490 needs to be set at 7 to prevent from power gating the memory. 491- The difference between halt and reboot is related if the power rail 492 that supplies to customer peripherals (such as Fan, HDMI-in, BT/Wi-Fi, 493 M.2, and Ethernet) is reset. 494 495.. figure:: images/ioc-image8.png 496 :width: 900px 497 :align: center 498 :name: ioc-heartbeat-flow 499 500 IOC Mediator - Heartbeat Flow 501 502- IOC DM will not maintain a watchdog timer for a heartbeat message. This 503 is because it already has other watchdog features, so the main use of 504 Heartbeat active command is to maintain the virtual wakeup reason 505 bitmap variable. 506- For Heartbeat, IOC mediator supports Heartbeat shutdown prepared, 507 Heartbeat active, Heartbeat shutdown delay, Heartbeat initial, and 508 Heartbeat Standby. 509- For SUS_STAT, IOC mediator supports invalid action and RAM refresh 510 action. 511- For Suppress heartbeat check will also be dropped directly. 512 513RTC 514+++ 515 516RTC timer is used to wake up the SoC when the timer is expired. (A use 517case is for an automatic software upgrade with a specific time.) RTC frame 518definition is as below. 519 520.. figure:: images/ioc-image9.png 521 :width: 600px 522 :align: center 523 524- The RTC command contains a relative time but not an absolute time. 525- Service VM lifecycle service will re-compute the time offset before it is 526 sent to the IOC firmware. 527 528.. figure:: images/ioc-image10.png 529 :width: 900px 530 :align: center 531 :name: ioc-rtc-flow 532 533 IOC Mediator - RTC Flow 534 535Signal Data 536----------- 537 538Signal channel is an API between the SoC and IOC for 539miscellaneous requirements. The process data includes all vehicle bus and 540carrier board data (GPIO, sensors, and so on). It supports 541transportation of single signals and group signals. Each signal consists 542of a signal ID (reference), its value, and its length. IOC and SoC need 543agreement on the definition of signal IDs that can be treated as API 544interface definitions. 545 546IOC signal type definitions are as below. 547 548.. figure:: images/ioc-image1.png 549 :width: 600px 550 :align: center 551 :name: ioc-process-data-svc-val 552 553 Process Data SVC Values 554 555.. figure:: images/ioc-image2.png 556 :width: 900px 557 :align: center 558 :name: ioc-med-signal-flow 559 560 IOC Mediator - Signal Flow 561 562- The IOC backend needs to emulate the channel open/reset/close message which 563 shouldn't be forwarded to the native cbc signal channel. The Service VM 564 signal related services should do a real open/reset/close signal channel. 565- Every backend should maintain a passlist for different VMs. The 566 passlist is hard coded. 567 568IOC mediator has two passlist tables, one is used for rx 569signals (SoC->IOC), and the other one is used for tx signals. The IOC 570mediator drops the single signals and group signals if the signals are 571not defined in the passlist. For multi signal, IOC mediator generates a 572new multi signal, which contains the signals in the passlist. 573 574.. figure:: images/ioc-image3.png 575 :width: 600px 576 :align: center 577 :name: ioc-med-multi-signal 578 579 IOC Mediator - Multi-Signal Passlist 580 581Raw Data 582-------- 583 584OEM raw channel only assigns to a specific User VM following that OEM 585configuration. The IOC Mediator will directly forward all read/write 586messages from IOC firmware to the User VM without any modification. 587 588 589IOC Mediator Usage 590****************** 591 592The Device Model configuration command syntax for IOC mediator is as 593follows:: 594 595 -i,[ioc_channel_path],[wakeup_reason] 596 -l,[lpc_port],[ioc_channel_path] 597 598The ``ioc_channel_path`` is an absolute path for communication between 599IOC mediator and UART DM. 600 601The ``lpc_port`` is ``com1`` or ``com2``. IOC mediator needs one unassigned 602lpc port for data transfer between User VM and Service VM. 603 604The ``wakeup_reason`` is the IOC mediator boot reason. Each bit represents 605one wakeup reason. 606 607For example, the following commands are used to enable the IOC feature. The 608initial wakeup reason is the ignition button and cbc_attach uses ttyS1 609for TTY line discipline in the User VM:: 610 611 -i /run/acrn/ioc_$vm_name,0x20 612 -l com2,/run/acrn/ioc_$vm_name 613 614 615 616
