# AMI Architecture                                                  
                                                                      
  ## Overview                                                         
                                                                      
  The AMR Management Interface (AMI) provides host-access to control  
  and manage the Advanced Management Controller (AMC).                
                                                                      
  It consists of:                                                     
                                                                      
  - A kernel driver, providing access to the AMR platform via the sGCQ
   (Simplified Generic Command Queue) interface.                      
                                                                      
  - An API (libami), providing a user-space abstraction to the kernel 
  driver.                                                             
                                                                      
  - A command line tool ([amitool](../deployment/ami-tool-guide.md)), 
  providing a human-readable interface to the API.                    
                                                                      
  **Note:** The AMI is an **example** design demonstrating how an AMR 
  host interface might be developed. It is **not** intended to be the 
  final implementation for AMR runtime management and control.        
                                                                      
  ## Key Components                                                   
                                                                      
  ### Kernel Driver                                                   
  - Communicates with AMC firmware via sGCQ                           
  - Manages PCIe configuration space and VSEC capabilities            
  - Provides character device interface for user-space access         
  - Implements sensor monitoring via Linux hwmon framework            
  - Handles AMC heartbeat monitoring and logging                      
                                                                      
  ### API Library (libami)                                            
  - C library providing programmatic access to AMC functionality      
  - Abstracts kernel driver interactions                              
  - Supports:                                                         
    - Device discovery and management                                 
    - Sensor data collection                                          
    - Manufacturing information access                                
    - Memory-mapped I/O operations                                    
    - EEPROM and QSFP module access                                   
    - PDI download and partition management                           
                                                                      
  ### Command Line Tool (amitool)                                     
  - User-friendly interface to libami API                             
  - Supports interactive and scripted operations                      
  - Provides commands for diagnostics, monitoring, and management     
                                                                      
  ## Communication Architecture                                       
                                                                      
  ### Request/Response Flow                                           
                                                                      
  The AMI uses a synchronous request/response model:                  
                                                                      
  1. **User Space** → API calls libami functions                      
  2. **libami** → Issues ioctl() to kernel driver                     
  3. **Kernel Driver** → Submits request via AMC Proxy                
  4. **AMC Proxy** → Sends request through sGCQ to AMC firmware       
  5. **Kernel Driver** → Blocks on completion variable                
  6. **AMC Firmware** → Processes request and sends response via sGCQ 
  7. **AMC Proxy** → Invokes callback (amc_proxy_callback)            
  8. **Kernel Driver** → Signals completion variable and unblocks     
  9. **libami** → Returns data to user application                    
                                                                      
  ### Timeouts                                                        
                                                                      
  - Most commands: 150 seconds                                        
  - Partition copy: 60 minutes                                        
  - Heartbeat: 0.5 seconds                                            
                                                                      
  ## Top Level Block Diagram                                          
                                                                      
  ![images/1107376981.png](../images/1107376981.png)                  
                                                                      
  ## Behavior                                                         
                                                                      
  ### Initialisation                                                  
                                                                      
  [Card Detection, Selection, and General                             
  Overview](Card-Detection,-Selection,-and-General-Overview)          
                                                                      
  ### Command Line Tool                                               
                                                                      
  [AMR Management Interface User Guide                                
  (amitool)](../deployment/ami-tool-guide.md)                         
                                                                      
  ### API Abstraction                                                 
                                                                      
  [AMI - API Description](ami-api.md)                                   
                                                                      
  ### Driver Interaction                                              
                                                                      
  [AMI - Kernel Driver Interaction](ami-kernel-driver.md)               
                                                                      
  ### Sensor Control                                                  
                                                                      
  [Sensors and Hardware Monitoring](card-detection.md)

  ### Device Reboot

  [AMI - Device Reboot](ami-hot-reset.md)                                   
                                                                      
  ## Version Compatibility                                            
                                                                      
  The AMI driver checks for compatible AMC firmware versions during   
  initialization. When version mismatch is detected, the driver       
  operates in compatibility mode with reduced functionality. For full 
  feature support, ensure AMC firmware version matches the AMI driver 
  version.