.. _pmu-ucode-cmds:

======================
PMU microcode commands
======================

.. contents::


Introduction
============

.. todo:: write me

Sample Implementation
---------------------

Example of setting up, running and handling potential error or timeout states.

Pseudocode::

        // Define interface to Falcon
        #define PDAEMON_SCRATCH0  0x10a040
        #define PDAEMON_SCRATCH1  0x10a044

        // Preparatory step
        #define PUNITS_UNK008     0x022408

        temp = nvkm_rd32(PUNITS_UNK008);
        nvkm_wr32((PUNITS_UNK008, temp | 0x2);

        // Prepare and send PMU microcode command

        command_id     = NV_UCODE_CMD_COMMAND_EID;  // 0x02
        command_status = NV_UCODE_CMD_STS_NEW;      // 0x01

        command_packet = command_id & 0xFFFFFFF | command_status;

        nvkm_wr32(PDAEMON_SCRATCH0, command_packet);

        // Loop whilst awaiting response
        for (i = 0; i < 50000; ++i) {
          pmu_command_response = nvkm_rd32(PDAEMON_SCRATCH0);

          pmu_command_response_status = pmu_command_response & 0xF0000000;

          if (pmu_command_response_status == 0x30000000)       // NV_UCODE_CMD_STS_COMPLETE
            break;
          if ( (pmu_command_response_status != 0x20000000) &&  // NV_UCODE_CMD_STS_PENDING
               (pmu_command_response_status != 0x10000000) )   // NV_UCODE_CMD_STS_NEW
          {
            RESPONSE_UNK1 = 1;
            break;
          }

          if (i == 50000-1)
            RESPONSE_UNK2 = 1;
        }

        if (RESPONSE_UNK1 || RESPONSE_UNK2) {
          // Handle timeouts
        }
        else {
          pmu_error_code = nvkm_rd32(PDAEMON_SCRATCH1);
          if (pmu_error_code & 0x7FFFFFFF) {
            // Handle error code
          }
          if ( (pmu_error_code & 0x80000000) == 0x80000000) {
            // getlog_cmd_do()
          }

          // Handle PMU command responses
        }


.. _pmu-ucode-cmds-opcodes:

Commands
========

XXX: Gaps expected. Based upon PMU microcode shipped with 390.67

========= ================================= =================================================================
Opcode    Name                              Description
========= ================================= =================================================================
0x00      NV_UCODE_CMD_COMMAND_NONE
0x01                                       
0x02      NV_UCODE_CMD_COMMAND_EID          EEPROM ID
0x03      NV_UCODE_CMD_COMMAND_ESI          Structure Init
0x04      NV_UCODE_CMD_COMMAND_ERD          Read EEPROM
0x05      NV_UCODE_CMD_COMMAND_EWR          Write EEPROM
0x06      NV_UCODE_CMD_COMMAND_ESE          Erase Sector
0x07      NV_UCODE_CMD_COMMAND_ECE          Erase Chip
0x08      NV_UCODE_CMD_COMMAND_RRD          Read priv register using PMU microcode
0x09      NV_UCODE_CMD_COMMAND_RWR          Write priv register using PMU microcode
0x0a      NV_UCODE_CMD_COMMAND_PREP
0x0b      NV_UCODE_CMD_COMMAND_CLOSE
0x0c      NV_UCODE_CMD_COMMAND_EPROT        Set Software Protection
0x0d      NV_UCODE_CMD_COMMAND_ERDSR        Read Status Register
0x0e      NV_UCODE_CMD_COMMAND_VV           Verify VBIOS
0x0f      NV_UCODE_CMD_COMMAND_ECID
0x10      NV_UCODE_CMD_COMMAND_LICVERIFY
0x11      NV_UCODE_CMD_COMMAND_BSI_INFO
0x12      NV_UCODE_CMD_COMMAND_HULKPROC
0x13      NV_UCODE_CMD_COMMAND_ARB
0x14      NV_UCODE_CMD_COMMAND_UNK14        Related to license file generation
0x15
0x16
0x17      NV_UCODE_CMD_COMMAND_OTP_READ
0x18      NV_UCODE_CMD_COMMAND_OTP_READLOCK
========= ================================= =================================================================


.. _pmu-ucode-cmds-status:

Command Status
==============

========= ================================ =================================================================
Opcode    Name                             Description
========= ================================ =================================================================
0x00      NV_UCODE_CMD_STS_NONE
0x01      NV_UCODE_CMD_STS_NEW
0x02      NV_UCODE_CMD_STS_PENDING
0x03      NV_UCODE_CMD_STS_COMPLETE
========= ================================ =================================================================


.. _pmu-ucode-cmds-error-code:

Error Codes
==============

XXX: Gaps expected. Based upon PMU microcode shipped with 390.67

========= ===================================================================== =================================================================
Opcode    Name                                                                  Description
========= ===================================================================== =================================================================
0x00      NV_UCODE_ERR_CODE_CMD_NOERROR                                         No error
0x01      NV_UCODE_ERR_CODE_CMD_TIMEOUT                                         Timeout occurred waiting for PMU
0x02      NV_UCODE_ERR_CODE_CMD_DEPENDENCY                                      May need other command to be issued first before carrying out this command
0x03      NV_UCODE_ERR_CODE_CMD_EID_RD_ERROR                                    EEPROM ID process failed
0x04      NV_UCODE_ERR_CODE_CMD_ERD_BUF_WR_ERROR                                Cannot write more bytes than size of image buffer
0x05      NV_UCODE_ERR_CODE_CMD_EWR_BUF_RD_ERROR                                Cannot read more bytes than size of image buffer
0x06      NV_UCODE_ERR_CODE_CMD_UNSUPPORTED_GPU                                 
0x07      NV_UCODE_ERR_CODE_CMD_UNSUPPORTED_COMMAND                             Invalid command
0x08      NV_UCODE_ERR_CODE_CMD_UNSUPPORTED_PARAMETER                           Supplied parameter is invalid or out of range
0x09      NV_UCODE_ERR_CODE_CMD_SECURE_REV_LOCK_VIOLATION
0x0a      NV_UCODE_ERR_CODE_LOAD_VBIOS_VERIFY_UCODE_FAIL
0x0b      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_DEBUG_FUSE_BOARD
0x0c      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_DEVID_FAIL 
0x0d      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_CERT_NOT_FOUND 
0x0e      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_CERT_PARSE_FAIL 
0x0f      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_CERT_VERIFY_FAIL 
0x10      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_HAT_FAIL 
0x11      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_BIOS_SIG_FAIL 
0x12      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_HULK_INIT_FAIL 
0x13      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_HULK_KA_NOT_FOUND 
0x14      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_HULK_TYPE_INVALID 
0x15      NV_UCODE_ERR_CODE_CMD_VBIOS_VERIFY_HULK_SIG_INVALID 
0x16      NV_UCODE_ERR_CODE_CERT_UNKNOWN_ERROR 
0x17      NV_UCODE_ERR_CODE_CERT_EXT_NOT_FOUND 
0x18      NV_UCODE_ERR_CODE_CERT_SIGNATURE_NOT_FOUND 
0x19      NV_UCODE_ERR_CODE_CERT_RSA1K_SIGNATURE_INVALID 
0x1a      NV_UCODE_ERR_CODE_CERT_EXT_NO_SUB_STRUCT_FOUND 
0x1b      NV_UCODE_ERR_CODE_CERT_UNSUPPORTED_VERSION 
0x1c      NV_UCODE_ERR_CODE_CERT_NO_EXTENSION_EXIST 
0x1d      NV_UCODE_ERR_CODE_CERT_T7QV1_PAYLOAD_SIZE_ERROR 
0x1e      NV_UCODE_ERR_CODE_CERT_T7_SW_FEATURE_PAYLOAD_SIZE_ERROR 
0x1f      NV_UCODE_ERR_CODE_CERT_T7_UNSUPPORTED_HW_STRUCT_VERSION 
0x20      NV_UCODE_ERR_CODE_CERT_T7_EXTENSIONS_NUM_EXCEED_LIMIT 
0x21      NV_UCODE_ERR_CODE_CERT_UGPU_PERSONALITY_MIS_MATCH 
0x22      NV_UCODE_ERR_CODE_CERT_UNKNOWN_HULK_FEATURE 
0x23      NV_UCODE_ERR_CODE_CERT_HULK_ECID_MISMATCH 
0x24      NV_UCODE_ERR_CODE_CERT_HULK_ECID_ENCODING_UNKNOWN 
0x25      NV_UCODE_ERR_CODE_ECID_ENCODING_ALGO_UNKNOWN 
0x26      NV_UCODE_ERR_CODE_CERT_T7_REG_OVERRIDE_TYPE_UNKNOWN 
0x27      NV_UCODE_ERR_CODE_LICVERIFY_UNSUPPORTED_LIC_TYPE 
0x28      NV_UCODE_ERR_CODE_UNSUPPORTED_CONFIG 
0x29      NV_UCODE_ERR_CODE_BSI_INFO_BRSS_INVALID 
0x2a      NV_UCODE_ERR_CODE_IMEM_TO_DMEM_COPY_INVALID_PARA 
0x2b      NV_UCODE_ERR_CODE_DERIVED_KEY_TYPE_INVALID 
0x2c      NV_UCODE_ERR_CODE_UCODE_NOT_IN_HS_MODE 
0x2d      NV_UCODE_ERR_CODE_VBIOS_DEVINIT_OFFSETS_INVALID 
0x2e      NV_UCODE_ERR_CODE_VBIOS_DEVINIT_SIG_INVALID
0x2f      NV_UCODE_ERR_CODE_CERT_HULK_DEVID_MISMATCH
0x30      NV_UCODE_ERR_CODE_CERT_HULK_NO_ID_MATCH_FOUND     
0x31      NV_UCODE_ERR_CODE_CERT_HULK_DATA_BUFFER_TOO_SMALL 
0x32      NV_UCODE_ERR_CODE_CERT_HULK_INFOROM_NOT_FOUND 
0x33      NV_UCODE_ERR_CODE_CERT_HULK_INFOROM_UL_GLOB_NOT_FOUND 
0x34      NV_UCODE_ERR_CODE_CERT_HULK_INFOROM_HLK_OBJ_NOT_VALID 
0x35      NV_UCODE_ERR_CODE_CERT_UGPU_LICENSE_PROCESSING_FAILED 
0x36      NV_UCODE_ERR_CODE_UGPU_PROCESSING_FAILED_INVALID_ULF_OBJECT 
0x37      NV_UCODE_ERR_CODE_UGPU_PROCESSING_FAILED_INVALID_UPR_OBJECT 
0x38      NV_UCODE_ERR_CODE_CERT20_INTBLK_VDPA_HEADER_INVALID 
0x39      NV_UCODE_ERR_CODE_CERT20_INTBLK_INT_SIG_HEADER_INVALID 
0x3a      NV_UCODE_ERR_CODE_CERT20_INTBLK_INT_SIG_CRYPTO_UNDEFINED 
0x3b      NV_UCODE_ERR_CODE_CERT20_VDPA_UNEXPECTED_MAJOR_TYPE 
0x3c      NV_UCODE_ERR_CODE_CERT20_VDPA_UNEXPECTED_MINOR_TYPE 
0x3d      NV_UCODE_ERR_CODE_CERT20_VDPA_ENTRY_SIZE_LARGER_THAN_DATA_BUFFER 
0x3e      NV_UCODE_ERR_CODE_CERT20_VDPA_UNEXPECTED_CODE_TYPE 
0x3f      NV_UCODE_ERR_CODE_CERT20_VDPA_NOT_FINALIZED 
0x40      NV_UCODE_ERR_CODE_CERT20_VDPA_SIG_INVALID 
0x41      NV_UCODE_ERR_CODE_CERT20_VDPA_ENTRY_NOT_FOUND 
0x42      NV_UCODE_ERR_CODE_CERT20_VDPA_CERT_INTBLK_MISMATCH 
0x43      NV_UCODE_ERR_CODE_CERT20_VDPA_ENTRY_FOUND_DATA_MISMATCH 
0x44      NV_UCODE_ERR_CODE_CERT20_VDPA_DATA_INVALID 
0x45      NV_UCODE_ERR_CODE_CERT20_VDPA_FLASH_SIZE_LARGER_THAN_EXPECTED 
0x46      NV_UCODE_ERR_CODE_CERT20_VDPA_DEVID_MISMATCH 
0x47      NV_UCODE_ERR_CODE_GPU_INITIALIZATION_TABLES_SIG_CHECK_FAILED          Also known as NV_UCODE_ERR_CODE_VBIOS_DEVINIT_TABLES_SIG_INVALID
0x48      NV_UCODE_ERR_CODE_GPU_INITIALIZATION_SCRIPTS_SIG_CHECK_FAILED         Also known as NV_UCODE_ERR_CODE_VBIOS_DEVINIT_SCRIPTS_SIG_INVALID 
0x49
0x4a      NV_UCODE_ERR_CODE_VERIFY_ENG_HULK_LICENSE_NOT_PRESENT 
0x4b      NV_UCODE_ERR_CODE_VERIFY_ENG_HULK_LICENSE_KA_NOT_FOUND
0x4c      NV_UCODE_ERR_CODE_VERIFY_ENG_HULK_LICENSE_TYPE_INVALID 
0x4d      NV_UCODE_ERR_CODE_VERIFY_ENG_HULK_3AES_SIG_MISMATCH_WITH_GPU_FUSE 
0x4e      NV_UCODE_ERR_CODE_VERIFY_ENG_HULK_NO_3AES_SIG 
0x4f      NV_UCODE_ERR_CODE_VERIFY_ENG_HULK_LICENSE_HULK_AES_SIG_INVALID 
0x50      NV_UCODE_ERR_CODE_VERIFY_ENG_HULK_LICENSE_NVF_ENG_AES_SIG_INVALID 
0x51      NV_UCODE_ERR_CODE_CHECK_ERASE_LICENSE_ERASE_DISALLOWED 
0x52      NV_UCODE_ERR_CODE_CMD_PREP_LICENSE_SIZE_OVERFLOW 
0x53      NV_UCODE_ERR_CODE_CMD_EWR_NO_ERASE_NOT_PERMITTED 
0x54      NV_UCODE_ERR_CODE_CMD_EWR_NO_VERIFY_NOT_PERMITTED 
0x55      NV_UCODE_ERR_CODE_CMD_ESE_NOT_PERMITTED 
0x56      NV_UCODE_ERR_CODE_CMD_ECE_NOT_PERMITTED 
0x57      NV_UCODE_ERR_CODE_CERT20_VDPA_UNEXPECTED_INSTANCE 
0x58      NV_UCODE_ERR_CODE_DEVID_MATCH_LIST_MORE_DEVIDS_THAN_BUFFERS 
0x59      NV_UCODE_ERR_CODE_DEVID_MATCH_LIST_SIG_INVALID 
0x5a      NV_UCODE_ERR_CODE_DEVID_MATCH_LIST_DEVID_MATCH_FAILED 
0x5b      NV_UCODE_ERR_CODE_DEVID_MATCH_LIST_DEVID_NOT_FOR_THE_GPU 
0x5c      NV_UCODE_ERR_CODE_DEVID_MATCH_LIST_DEVID_OUT_OF_HAT_COVERAGE 
0x5d      NV_UCODE_ERR_CODE_PUSH_POLL_DMEM_COPY_BUFFER_OVERFLOW 
0x5e      NV_UCODE_ERR_CODE_PUSH_POLL_DMEM_COPY_DATA_OUT_OF_RANGE 
0x5f      NV_UCODE_ERR_CODE_CERT20_INTBLK_VDPA_BLOCK_OVERSIZE 
0x60
0x61
0x62
0x63
0x64
0x65
0x66
0x67
0x68
0x69
0x6a
0x6b
0x6c      NV_UCODE_ERR_CODE_CMD_EWR_OK_TO_FLASH_CHECK_FAILED 
0x6e      NV_UCODE_ERR_CODE_HW_SPI_TIMEOUT
0x6f
0x70
0x71
0x72
0x73      NV_UCODE_ERR_CODE_CERT21_FMT_HAT_ENTRY_NUMBER_INVALID
0x74      NV_UCODE_ERR_CODE_CERT21_FMT_HAT_ENTRY_FOMMATTER_TOO_LONG
0x75      NV_UCODE_ERR_CODE_CERT21_FMT_FORMATTER_DATA_BLOCK_OVER_SIZE
0x76      NV_UCODE_ERR_CODE_CERT21_FMT_UNEXPECTED_FORMATTER_TYPE
0x77      NV_UCODE_ERR_CODE_CERT21_FMT_EXCEED_FORMATTER_LENGTH
0x78      NV_UCODE_ERR_CODE_EEPROM_OTP_DEVICE_UNSUPPORTED
0x79      NV_UCODE_ERR_CODE_EEPROM_OTP_ERASE_NOT_PRESENT
0x7a      NV_UCODE_ERR_CODE_EEPROM_OTP_FACTORY_LOCK_NOT_PRESENT
0x7b      NV_UCODE_ERR_CODE_EEPROM_OTP_FACTORY_REGION_NOT_PRESENT
0x7c      NV_UCODE_ERR_CODE_EEPROM_OTP_USER_ADDRESS_OUT_OF_RANGE
0x7d      NV_UCODE_ERR_CODE_EEPROM_OTP_FACTORY_ADDRESS_OUT_OF_RANGE
0x7f
0x80
0x81
0x82      NV_UCODE_ERR_CODE_PLAY_READY_PDUB_SIG_INVALID
0x83      NV_UCODE_ERR_CODE_PLAY_READY_PDUB_ENTRY_NOT_FOUND
0x84      NV_UCODE_ERR_CODE_PLAY_READY_EXIT_FOR_DEVINIT_NOT_RUN
0x85      NV_UCODE_ERR_CODE_PLAY_READY_PDUB_PRIV_CONN_STATE_MISMATCH
0x86      NV_UCODE_ERR_CODE_PLAY_READY_OTP_ENTRY_NOT_AVAILABLE
0x87      NV_UCODE_ERR_CODE_PLAY_READY_SEC2_MUTEX_ACQUIRE_FAILED
0x88      NV_UCODE_ERR_CODE_PLAY_READY_SEC2_MUTEX_RELEASE_FAILED
0x89      NV_UCODE_ERR_CODE_VERIFY_ENG_LICENSE_INCORRECT_TYPE
0x8a      NV_UCODE_ERR_CODE_INVALID_FALCON
0x8b      NV_UCODE_ERR_CODE_NUM_REPAIR_ENTRIES_EXCEEDS_MAX_ALLOWED
0x8c      NV_UCODE_ERR_CODE_INVALID_REPAIR_OBJECT
0x8d      NV_UCODE_ERR_CODE_BCRT2x_CERT_BUFFER_OVERFLOW
0x8e      NV_UCODE_ERR_CODE_BCRT2x_HAT_ENTRIES_BUFFER_OVERFLOW
0x8f      NV_UCODE_ERR_CODE_BCRT2x_HAT_HEADER_OVER_SIZE
0x90      NV_UCODE_ERR_CODE_BCRT2x_RSA_SIG_HEADER_OVER_SIZE
0x91
0x92      NV_UCODE_ERR_CODE_BCRT2X_CERT_BLOCK_VERSION_UNEXPECTED
0x93      NV_UCODE_ERR_CODE_BCRT2X_CERT_CONTROL_HEADER_OVERFLOW
0x94      NV_UCODE_ERR_CODE_BCRT2X_MAX_SECURITYZONE_REACHED
0x95      NV_UCODE_ERR_CODE_BCRT2X_SECURITYZONE_SIGNATURES_SIZE_CHECK_FAILED
0x96      NV_UCODE_ERR_CODE_BCRT2X_SECURITYZONE_SIG_STRUCT_SIZE_CHECK_FAILED
0x97      NV_UCODE_ERR_CODE_BCRT2X_SECURITYZONE_SIG_ZONE_NUM_INVALID
0x98      NV_UCODE_ERR_CODE_BCRT2X_SECURITYZONE_SIG_ALGO_INVALID
0x99      NV_UCODE_ERR_CODE_BCRT2X_SECURITYZONE_BUILT_IN_SEC_ZONE_MISSING
0x9a      NV_UCODE_ERR_CODE_BCRT2X_SECURITYZONE_SIGNATURE_INVALID
0x9b      NV_UCODE_ERR_CODE_BCRT2X_SECURITYZONE_SIG_NOT_FOUND
0x9c      NV_UCODE_ERR_CODE_BCRT2X_VDPA_ENTRY_VERIFY_HASH_MISMATCH
0x9d      NV_UCODE_ERR_CODE_BCRT2X_VDPA_INTBLK_ENTRIES_NUM_EXCEED_MAX
========= ===================================================================== =================================================================
