1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /** 3 * Copyright 2019-2024 NXP 4 * 5 * KEYWORDS: micro-power uPower driver API 6 * ----------------------------------------------------------------------------- 7 * PURPOSE: uPower driver API 8 * ----------------------------------------------------------------------------- 9 * PARAMETERS: 10 * PARAM NAME RANGE:DESCRIPTION: DEFAULTS: UNITS 11 * ----------------------------------------------------------------------------- 12 * REUSE ISSUES: no reuse issues 13 */ 14 #ifndef UPWR_API_H 15 #define UPWR_API_H 16 17 #include "upmu.h" 18 #include "upower_soc_defs.h" 19 /****************************************************************************** 20 * uPower API Overview and Concepts 21 * 22 * This API is intended to be used by the OS drivers (Linux, FreeRTOS etc) 23 * as well as bare metal drivers to command and use services from the uPower. 24 * It aims to be OS-independent. 25 * 26 * The API functions fall in 3 categories: 27 * - initialization/start-up 28 * - service requests 29 * - auxiliary 30 * 31 * The communication with the uPower is mostly made through the Message Unit 32 * (MU) IP. uPower provides one MU for each CPU cluster in a different 33 * power domain. An API instance runs on each CPU cluster. 34 * 35 * The API assumes each SoC power domain/CPU cluster receives 2 interrupts 36 * from the uPower MU: 37 * 1. Tx/Rx, which is issued on both transmission and reception 38 * 2. Exception interrupt, to handle critical alams, catastrophic errors, etc. 39 * This interrupt should have a high priority, preferably an NMI. 40 * 41 * The normal uPower operation is done by service requests. There is an API 42 * function for each service request, and all service requests send back a 43 * response, at least to indicate success/failure. 44 * The service request functions are non-blocking, and their completion can be 45 * tracked in two ways: 46 * 1. by a callback, registered when the service request call is made by 47 * passing the callback function pointer; a NULL pointer may be passed, 48 * in which case no callback is made. 49 * 2. by polling, using the auxiliary functions upwr_req_status or 50 * upwr_poll_req_status; 51 * polling must be used if no callback is registered, but callbacks and 52 * polling are completely independent. 53 * 54 * Note: a service request must not be started from a callback. 55 * 56 * uPower service requests are classified in Service Groups. 57 * Each Service Group has a set of related functions, named upwr_XXX_, 58 * where XXX is a 3-letter service group mnemonic. The service groups are: 59 * - Exception Service Group - upwr_xcp_* 60 * ~ gathers functions that deal with errors and other processes outside 61 * the functional scope. 62 * - Power Management Service Group - upwr_pwm_* 63 * ~ functions to control switches, configure power modes, set internal voltage etc 64 * - Delay Measurement Service Group - upwr_dlm_* 65 * ~ delay measurements function using the process monitor and delay meter 66 * - Voltage Measurement Service Group - upwr_vtm_* 67 * ~ functions for voltage measurements, comparisons, alarms, power meter, set PMIC rail voltage 68 * - Temperature Measurement Service Group - upwr_tpm_* 69 * ~ functions for temperature measurements, comparisons, alarms 70 * - Current Measurement Service Group - upwr_crm_* 71 * ~ functions for current and charge measurement 72 * - Diagnostic Service Group - upwr_dgn_* 73 * ~ functions for log configuration and statistics collecting 74 * 75 * Service requests follow this "golden rule": 76 * *** No two requests run simultaneously for the same service group, 77 * on the same domain *** 78 * They can run simultaneously on different domains (RTD/APD), and can also run 79 * simultaneously if belong to different service groups (even on same domain). 80 * Therefore, requests to the same service group on the same domain must be 81 * serialized. A service request call returns error if there is another request 82 * on the same service group pending, waiting a response (on the same domain). 83 * 84 * A request for continuous service does not block the service group. 85 * For instance, a request to "measure the temperature each 10 miliseconds" 86 * responds quickly, unlocks the service group, and the temperature 87 * continues to be measured as requested, every 10 miliseconds from then on. 88 * 89 * Service Groups have a fixed priority in the API, from higher to lower: 90 * 1. Exception 91 * 2. Power Management 92 * 3. Delay Measurement 93 * 4. Voltage Measurement 94 * 5. Current Measurement 95 * 6. Temperature Measurement 96 * 7. Diagnostics 97 * 98 * The priority above only affects the order in which requests are sent to the 99 * uPower firmware: request to the higher priority Service Group is sent first, 100 * even if the call was made later, if there is an MU transmission pending, 101 * blocking it. The service priorities in the firmware depend on other factors. 102 * 103 * Services are requested using API functions. A service function returns with 104 * no error if a request was successfully made, but it doesn't mean the service 105 * was completed. The service is executed asynchronously, and returns a result 106 * (at least success/fail) via a callback or polling for service status. 107 * The possible service response codes are: 108 * - UPWR_RESP_OK = 0, : no error 109 * - UPWR_RESP_SG_BUSY : service group is busy 110 * - UPWR_RESP_SHUTDOWN : services not up or shutting down 111 * - UPWR_RESP_BAD_REQ : invalid request (usually invalid argumnents) 112 * - UPWR_RESP_BAD_STATE : system state doesn't allow perform the request 113 * - UPWR_RESP_UNINSTALLD : service or function not installed 114 * - UPWR_RESP_UNINSTALLED : service or function not installed (alias) 115 * - UPWR_RESP_RESOURCE : resource not available 116 * - UPWR_RESP_TIMEOUT : service timeout 117 */ 118 119 /** 120 * upwr_callb()-generic function pointer for a request return callback; 121 * @sg: request service group 122 * @func: service request function id. 123 * @errcode: error code. 124 * @ret: return value, if any. Note that a request may return a value even if 125 * service error is returned (errcode != UPWR_RESP_OK); that is dependent on 126 * the specific service. 127 * 128 * Context: no sleep, no locks taken/released. 129 * Return: none (void) 130 */ 131 typedef void (*upwr_callb)(upwr_sg_t sg, uint32_t func, 132 upwr_resp_t errcode, ...); 133 134 /**--------------------------------------------------------------- 135 * INITIALIZATION, CONFIGURATION 136 * 137 * A reference uPower initialization sequence goes as follows: 138 * 139 * 1. host CPU calls upwr_init. 140 * 2. (optional) host checks the ROM version and SoC code calling upwr_vers(...) 141 * and optionally performs any configuration or workaround accordingly. 142 * 3. host CPU calls upwr_start to start the uPower services, passing a 143 * service option number. 144 * If no RAM code is loaded or it has no service options, the launch option 145 * number passed must be 0, which will start the services available in ROM. 146 * upwr_start also receives a pointer to a callback called by the API 147 * when the firmware is ready to receive service requests. 148 * The callback may be replaced by polling, calling upwr_req_status in a loop 149 * or upwr_poll_req_status; in this case the callback pointer may be NULL. 150 * A host may call upwr_start even if the services were already started by 151 * any host: if the launch option is the same, the response will be ok, 152 * but will indicate error if the services were already started with a 153 * different launch option. 154 * 4. host waits for the callback calling, or polling finishing; 155 * if no error is returned, it can start making service calls using the API. 156 * 157 * Variations on that reference sequence are possible: 158 * - the uPower services can be started using the ROM code only, which includes 159 * the basic Power Management services, among others, with launch option 160 * number = 0. 161 * The code RAM can be loaded while these services are running and, 162 * when the loading is done, the services can be re-started with these 2 163 * requests executed in order: upwr_xcp_shutdown and upwr_start, 164 * using the newly loaded RAM code (launch option > 0). 165 * 166 * NOTE: the initialization call upwr_init is not effective and 167 * returns error when called after the uPower services are started. 168 */ 169 170 /** 171 * upwr_init() - API initialization; must be the first API call after reset. 172 * @domain: SoC-dependent CPU domain id; identifier used by the firmware in 173 * many services. Defined by SoC-dependent type soc_domain_t found in 174 * upower_soc_defs.h. 175 * @muptr: pointer to the MU instance. 176 * @mallocptr: pointer to the memory allocation function 177 * @physaddrptr: pointer to the function to convert pointers to 178 * physical addresses. If NULL, no conversion is made (pointer=physical address) 179 * @isrinstptr: pointer to the function to install the uPower ISR callbacks; 180 * the function receives the pointers to the MU tx/rx and Exception ISRs 181 * callbacks, which must be called from the actual system ISRs. 182 * The function pointed by isrinstptr must also enable the interrupt at the 183 * core/interrupt controller, but must not enable the interrupt at the MU IP. 184 * The system ISRs are responsible for dealing with the interrupt controller, 185 * performing any other context save/restore, and any other housekeeping. 186 * @lockptr: pointer to a function that prevents MU interrupts (if argrument=1) 187 * or allows it (if argument=0). The API calls this function to make small 188 * specific code portions thread safe. Only MU interrupts must be avoided, 189 * the code may be suspended for other reasons. 190 * If no MU interrupts can happen during the execution of an API call or 191 * callback, even if enabled, for some other reason (e.g. interrupt priority), 192 * then this argument may be NULL. 193 * 194 * Context: no sleep, no locks taken/released. 195 * Return: 0 if ok, 196 * -1 if failed to allocate memory, or use some other resource. 197 * -2 if any argument is invalid. 198 * -3 if failed to send the ping message. 199 * -4 if failed to receive the initialization message, or was invalid 200 */ 201 202 /* malloc function ptr */ 203 typedef void* (*upwr_malloc_ptr_t)(unsigned int size); 204 205 /* pointer->physical address conversion function ptr */ 206 typedef void* (*upwr_phyadr_ptr_t)(const void *addr); 207 208 typedef uint32_t upwr_api_state_t; 209 210 extern volatile upwr_api_state_t api_state; 211 212 /* 213 * upwr_lock_ptr_t: pointer to a function that prevents MU interrupts 214 * (if argrument lock=1) or allows it (if argument lock=0). 215 * The API calls this function to make small specific code portions thread safe. 216 * Only MU interrupts must be avoided, the code may be suspended for other 217 * reasons. 218 */ 219 typedef void (*upwr_lock_ptr_t)(int lock); 220 221 typedef void (*upwr_isr_callb)(void); 222 223 typedef void (*upwr_inst_isr_ptr_t)(upwr_isr_callb txrx_isr, 224 upwr_isr_callb excp_isr); 225 void upwr_start_callb(void); 226 227 int upwr_init(soc_domain_t domain, struct MU_t *muptr, 228 const upwr_malloc_ptr_t mallocptr, 229 const upwr_phyadr_ptr_t phyadrptr, 230 const upwr_inst_isr_ptr_t isrinstptr, 231 const upwr_lock_ptr_t lockptr); 232 233 /** 234 * upwr_start() - Starts the uPower services. 235 * @launchopt: a number to select between multiple launch options, 236 * that may define, among other things, which services will be started, 237 * or which services implementations, features etc. 238 * launchopt = 0 selects a subset of services implemented in ROM; 239 * any other number selects service sets implemented in RAM, launched 240 * by the firmware function ram_launch; if an invalid launchopt value is passed, 241 * no services are started, and the callback returns error (see below). 242 * @rdycallb: pointer to the callback to be called when the uPower is ready 243 * to receive service requests. NULL if no callback needed. 244 * The callback receives as arguments the RAM firmware version numbers. 245 * If all 3 numbers (vmajor, vminor, vfixes) are 0, that means the 246 * service launching failed. 247 * Firmware version numbers will be the same as ROM if launchopt = 0, 248 * selecting the ROM services. 249 * 250 * upwr_start can be called by any domain even if the services are already 251 * started: it has no effect, returning success, if the launch option is the 252 * same as the one that actually started the service, and returns error if 253 * called with a different option. 254 * 255 * A callback can be optionally registered, and will be called upon the arrival 256 * of the request response from the uPower firmware, telling if it succeeded or 257 * not. 258 * A callback may not be registered (NULL pointer), in which case polling has 259 * to be used to check the response, by calling upwr_req_status or 260 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 261 * 262 * Context: no sleep, no locks taken/released. 263 * Return: 0 if ok, 264 * -1 if a resource failed, 265 * -2 if the domain passed is the same as the caller, 266 * -3 if called in an invalid API state 267 */ 268 269 extern void upwr_txrx_isr(void); 270 271 typedef void (*upwr_rdy_callb)(uint32_t vmajor, uint32_t vminor, uint32_t vfixes); 272 273 int upwr_start(uint32_t launchopt, const upwr_rdy_callb rdycallb); 274 275 276 /**--------------------------------------------------------------- 277 * EXCEPTION SERVICE GROUP 278 */ 279 280 /** 281 * upwr_xcp_config() - Applies general uPower configurations. 282 * @config: pointer to the uPower SoC-dependent configuration struct 283 * upwr_xcp_config_t defined in upower_soc_defs.h. NULL may be passed, meaning 284 * a request to read the configuration, in which case it appears in the callback 285 * argument ret, or can be pointed by argument retptr in the upwr_req_status and 286 * upwr_poll_req_status calls, casted to upwr_xcp_config_t. 287 * @callb: pointer to the callback to be called when the uPower has finished 288 * the configuration, or NULL if no callback needed (polling used instead). 289 * 290 * Some configurations are targeted for a specific domain (see the struct 291 * upwr_xcp_config_t definition in upower_soc_defs.h); this call has implicit 292 * domain target (the same domain from which is called). 293 * 294 * The return value is always the current configuration value, either in a 295 * read-only request (config = NULL) or after setting a new configuration 296 * (non-NULL config). 297 * 298 * A callback can be optionally registered, and will be called upon the arrival 299 * of the request response from the uPower firmware, telling if it succeeded or 300 * not. 301 * A callback may not be registered (NULL pointer), in which case polling has 302 * to be used to check the response, by calling upwr_req_status or 303 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 304 * 305 * Context: no sleep, no locks taken/released. 306 * Return: 0 if ok, 307 * -1 if service group is busy, 308 * -3 if called in an invalid API state 309 */ 310 311 int upwr_xcp_config(const upwr_xcp_config_t *config, const upwr_callb callb); 312 313 /** 314 * upwr_xcp_sw_alarm() - Makes uPower issue an alarm interrupt to given domain. 315 * @domain: identifier of the domain to alarm. Defined by SoC-dependent type 316 * soc_domain_t found in upower_soc_defs.h. 317 * @code: alarm code. Defined by SoC-dependent type upwr_alarm_t found in 318 * upower_soc_defs.h. 319 * @callb: pointer to the callback to be called when the uPower has finished 320 * the alarm, or NULL if no callback needed (polling used instead). 321 * 322 * The function requests the uPower to issue an alarm of the given code as if 323 * it had originated internally. This service is useful mainly to test the 324 * system response to such alarms, or to make the system handle a similar alarm 325 * situation detected externally to uPower. 326 * 327 * The system ISR/code handling the alarm may retrieve the alarm code by calling 328 * the auxiliary function upwr_alarm_code. 329 * 330 * A callback can be optionally registered, and will be called upon the arrival 331 * of the request response from the uPower firmware, telling if it succeeded or 332 * not. 333 * A callback may not be registered (NULL pointer), in which case polling has 334 * to be used to check the response, by calling upwr_req_status or 335 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 336 * 337 * Context: no sleep, no locks taken/released. 338 * Return: 0 if ok, 339 * -1 if service group is busy, 340 * -3 if called in an invalid API state 341 */ 342 343 int upwr_xcp_sw_alarm(soc_domain_t domain, upwr_alarm_t code, 344 const upwr_callb callb); 345 346 /** 347 * upwr_xcp_set_ddr_retention() - M33/A35 can use this API to set/clear ddr retention 348 * @domain: identifier of the caller domain. 349 * soc_domain_t found in upower_soc_defs.h. 350 * @enable: true, means that set ddr retention, false clear ddr retention. 351 * @callb: NULL 352 * 353 * A callback may not be registered (NULL pointer), in which case polling has 354 * to be used to check the response, by calling upwr_req_status or 355 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 356 * 357 * Context: no sleep, no locks taken/released. 358 * Return: 0 if ok, 359 * -1 if service group is busy, 360 * -3 if called in an invalid API state 361 */ 362 363 int upwr_xcp_set_ddr_retention(soc_domain_t domain, uint32_t enable, 364 const upwr_callb callb); 365 366 /** 367 * upwr_xcp_set_mipi_dsi_ena() - M33/A35 can use this API to set/clear mipi dsi ena 368 * @domain: identifier of the caller domain. 369 * soc_domain_t found in upower_soc_defs.h. 370 * @enable: true, means that set ddr retention, false clear ddr retention. 371 * @callb: NULL 372 * 373 * A callback may not be registered (NULL pointer), in which case polling has 374 * to be used to check the response, by calling upwr_req_status or 375 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 376 * 377 * Context: no sleep, no locks taken/released. 378 * Return: 0 if ok, 379 * -1 if service group is busy, 380 * -3 if called in an invalid API state 381 */ 382 383 int upwr_xcp_set_mipi_dsi_ena(soc_domain_t domain, uint32_t enable, 384 const upwr_callb callb); 385 386 /** 387 * upwr_xcp_get_mipi_dsi_ena() - M33/A35 can use this API to get mipi dsi ena status 388 * @domain: identifier of the caller domain. 389 * soc_domain_t found in upower_soc_defs.h. 390 * @callb: NULL 391 * 392 * A callback may not be registered (NULL pointer), in which case polling has 393 * to be used to check the response, by calling upwr_req_status or 394 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 395 * 396 * Context: no sleep, no locks taken/released. 397 * Return: 0 if ok, 398 * -1 if service group is busy, 399 * -3 if called in an invalid API state 400 */ 401 402 int upwr_xcp_get_mipi_dsi_ena(soc_domain_t domain, const upwr_callb callb); 403 404 /** 405 * upwr_xcp_set_osc_mode() - M33/A35 can use this API to set uPower OSC mode 406 * @domain: identifier of the caller domain. 407 * soc_domain_t found in upower_soc_defs.h. 408 * @osc_mode, 0 means low frequency, not 0 means high frequency. 409 * @callb: NULL 410 * 411 * A callback may not be registered (NULL pointer), in which case polling has 412 * to be used to check the response, by calling upwr_req_status or 413 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 414 * 415 * Context: no sleep, no locks taken/released. 416 * Return: 0 if ok, 417 * -1 if service group is busy, 418 * -3 if called in an invalid API state 419 */ 420 int upwr_xcp_set_osc_mode(soc_domain_t domain, uint32_t osc_mode, 421 const upwr_callb callb); 422 423 /** 424 * upwr_xcp_set_rtd_use_ddr() - M33 call this API to inform uPower, M33 is using ddr 425 * @domain: identifier of the caller domain. 426 * soc_domain_t found in upower_soc_defs.h. 427 * @is_use_ddr: not 0, true, means that RTD is using ddr. 0, false, means that, RTD 428 * is not using ddr. 429 * @callb: NULL 430 * 431 * A callback may not be registered (NULL pointer), in which case polling has 432 * to be used to check the response, by calling upwr_req_status or 433 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 434 * 435 * Context: no sleep, no locks taken/released. 436 * Return: 0 if ok, 437 * -1 if service group is busy, 438 * -3 if called in an invalid API state 439 */ 440 int upwr_xcp_set_rtd_use_ddr(soc_domain_t domain, uint32_t is_use_ddr, 441 const upwr_callb callb); 442 443 /** 444 * upwr_xcp_set_rtd_apd_llwu() - M33/A35 can use this API to set/clear rtd_llwu apd_llwu 445 * @domain: set which domain (RTD_DOMAIN, APD_DOMAIN) LLWU. 446 * soc_domain_t found in upower_soc_defs.h. 447 * @enable: true, means that set rtd_llwu or apd_llwu, false clear rtd_llwu or apd_llwu. 448 * @callb: NULL 449 * 450 * A callback may not be registered (NULL pointer), in which case polling has 451 * to be used to check the response, by calling upwr_req_status or 452 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 453 * 454 * Context: no sleep, no locks taken/released. 455 * Return: 0 if ok, 456 * -1 if service group is busy, 457 * -3 if called in an invalid API state 458 */ 459 int upwr_xcp_set_rtd_apd_llwu(soc_domain_t domain, uint32_t enable, 460 const upwr_callb callb); 461 /** 462 * upwr_xcp_shutdown() - Shuts down all uPower services and power mode tasks. 463 * @callb: pointer to the callback to be called when the uPower has finished 464 * the shutdown, or NULL if no callback needed 465 * (polling used instead). 466 * 467 * A callback can be optionally registered, and will be called upon the arrival 468 * of the request response from the uPower firmware, telling if it succeeded or 469 * not. 470 * A callback may not be registered (NULL pointer), in which case polling has 471 * to be used to check the response, by calling upwr_req_status or 472 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 473 * 474 * At the callback the uPower/API is back to initialization/start-up phase, 475 * so service request calls return error. 476 * 477 * Context: no sleep, no locks taken/released. 478 * Return: 0 if ok, 479 * -1 if service group is busy, 480 * -3 if called in an invalid API state 481 */ 482 int upwr_xcp_shutdown(const upwr_callb callb); 483 484 /** 485 * upwr_xcp_i2c_access() - Performs an access through the uPower I2C interface. 486 * @addr: I2C slave address, up to 10 bits. 487 * @data_size: determines the access direction and data size in bytes, up to 4; 488 * negetive data_size determines a read access with size -data_size; 489 * positive data_size determines a write access with size data_size; 490 * data_size=0 is invalid, making the service return error UPWR_RESP_BAD_REQ. 491 * @subaddr_size: size of the sub-address in bytes, up to 4; if subaddr_size=0, 492 * no subaddress is used. 493 * @subaddr: sub-address, only used if subaddr_size > 0. 494 * @wdata: write data, up to 4 bytes; ignored if data_size < 0 (read) 495 * @callb: pointer to the callback to be called when the uPower has finished 496 * the access, or NULL if no callback needed 497 * (polling used instead). 498 * 499 * A callback can be optionally registered, and will be called upon the arrival 500 * of the request response from the uPower firmware, telling if it succeeded or 501 * not. 502 * A callback may not be registered (NULL pointer), in which case polling has 503 * to be used to check the response, by calling upwr_req_status or 504 * upwr_poll_req_status, using UPWR_SG_EXCEPT as the service group argument. 505 * 506 * The service performs a read (data_size < 0) or a write (data_size > 0) of 507 * up to 4 bytes on the uPower I2C interface. The data read from I2C comes via 508 * the callback argument ret, or written to the variable pointed by retptr, 509 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 510 * ret (or *retptr) also returns the data written on writes. 511 * 512 * Sub-addressing is supported, with sub-address size determined by the argument 513 * subaddr_size, up to 4 bytes. Sub-addressing is not used if subaddr_size=0. 514 * 515 * Context: no sleep, no locks taken/released. 516 * Return: 0 if ok, 517 * -1 if service group is busy, 518 * -3 if called in an invalid API state 519 */ 520 int upwr_xcp_i2c_access(uint16_t addr, int8_t data_size, uint8_t subaddr_size, 521 uint32_t subaddr, uint32_t wdata, 522 const upwr_callb callb); 523 524 525 /**--------------------------------------------------------------- 526 * POWER MANAGEMENT SERVICE GROUP 527 */ 528 529 /** 530 * upwr_pwm_dom_power_on() - Commands uPower to power on the platform of other 531 * domain (not necessarily its core(s)); does not release the core reset. 532 * @domain: identifier of the domain to power on. Defined by SoC-dependent type 533 * soc_domain_t found in upower_soc_defs.h. 534 * @boot_start: must be 1 to start the domain core(s) boot(s), releasing 535 * its (their) resets, or 0 otherwise. 536 * @pwroncallb: pointer to the callback to be called when the uPower has 537 * finished the power on procedure, or NULL if no callback needed 538 * (polling used instead). 539 * 540 * A callback can be optionally registered, and will be called upon the arrival 541 * of the request response from the uPower firmware, telling if it succeeded or 542 * not. 543 * A callback may not be registered (NULL pointer), in which case polling has 544 * to be used to check the response, by calling upwr_req_status or 545 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 546 * 547 * Context: no sleep, no locks taken/released. 548 * Return: 0 if ok, 549 * -1 if service group is busy, 550 * -2 if the domain passed is the same as the caller, 551 * -3 if called in an invalid API state 552 */ 553 int upwr_pwm_dom_power_on(soc_domain_t domain, int boot_start, 554 const upwr_callb pwroncallb); 555 556 /** 557 * upwr_pwm_boot_start() - Commands uPower to release the reset of other CPU(s), 558 * starting their boots. 559 * @domain: identifier of the domain to release the reset. Defined by 560 * SoC-dependent type soc_domain_t found in upower_soc_defs.h. 561 * @bootcallb: pointer to the callback to be called when the uPower has finished 562 * the boot start procedure, or NULL if no callback needed 563 * (polling used instead). 564 * 565 * A callback can be optionally registered, and will be called upon the arrival 566 * of the request response from the uPower firmware, telling if it succeeded or 567 * not. 568 * A callback may not be registered (NULL pointer), in which case polling has 569 * to be used to check the response, by calling upwr_req_status or 570 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 571 * 572 * The callback calling doesn't mean the CPUs boots have finished: 573 * it only indicates that uPower released the CPUs resets, and can receive 574 * other power management service group requests. 575 * 576 * Context: no sleep, no locks taken/released. 577 * Return: 0 if ok, 578 * -1 if service group is busy, 579 * -2 if the domain passed is the same as the caller, 580 * -3 if called in an invalid API state 581 */ 582 int upwr_pwm_boot_start(soc_domain_t domain, const upwr_callb bootcallb); 583 584 /** 585 * upwr_pwm_param() - Changes Power Management parameters. 586 * @param: pointer to a parameter structure upwr_pwm_param_t, SoC-dependent, 587 * defined in upwr_soc_defines.h. NULL may be passed, meaning 588 * a request to read the parameter set, in which case it appears in the callback 589 * argument ret, or can be pointed by argument retptr in the upwr_req_status and 590 * upwr_poll_req_status calls, casted to upwr_pwm_param_t. 591 * @callb: response callback pointer; NULL if no callback needed. 592 * 593 * The return value is always the current parameter set value, either in a 594 * read-only request (param = NULL) or after setting a new parameter 595 * (non-NULL param). 596 * 597 * Some parameters may be targeted for a specific domain (see the struct 598 * upwr_pwm_param_t definition in upower_soc_defs.h); this call has implicit 599 * domain target (the same domain from which is called). 600 * 601 * A callback can be optionally registered, and will be called upon the arrival 602 * of the request response from the uPower firmware, telling if it succeeded or 603 * not. 604 * A callback may not be registered (NULL pointer), in which case polling has 605 * to be used to check the response, by calling upwr_req_status or 606 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 607 * 608 * Context: no sleep, no locks taken/released. 609 * Return: 0 if ok, 610 * -1 if service group is busy, 611 * -3 if called in an invalid API state 612 */ 613 int upwr_pwm_param(upwr_pwm_param_t *param, const upwr_callb callb); 614 615 /** 616 * upwr_pwm_chng_reg_voltage() - Changes the voltage at a given regulator. 617 * @reg: regulator id. 618 * @volt: voltage value; value unit is SoC-dependent, converted from mV by the 619 * macro UPWR_VOLT_MILIV, or from micro-Volts by the macro UPWR_VOLT_MICROV, 620 * both macros in upower_soc_defs.h 621 * @callb: response callback pointer; NULL if no callback needed. 622 * 623 * The function requests uPower to change the voltage of the given regulator. 624 * The request is executed if arguments are within range, with no protections 625 * regarding the adequate voltage value for the given domain process, 626 * temperature and frequency. 627 * 628 * A callback can be optionally registered, and will be called upon the arrival 629 * of the request response from the uPower firmware, telling if it succeeded 630 * or not. 631 * 632 * A callback may not be registered (NULL pointer), in which case polling has 633 * to be used to check the response, by calling upwr_req_status or 634 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 635 * 636 * Context: no sleep, no locks taken/released. 637 * Return: 0 if ok, 638 * -1 if service group is busy, 639 * -3 if called in an invalid API state 640 * Note that this is not the error response from the request itself: 641 * it only tells if the request was successfully sent to the uPower. 642 */ 643 int upwr_pwm_chng_reg_voltage(uint32_t reg, uint32_t volt, upwr_callb callb); 644 645 /** 646 * upwr_pwm_freq_setup() - Determines the next frequency target for a given 647 * domain and current frequency. 648 * @domain: identifier of the domain to change frequency. Defined by 649 * SoC-dependent type soc_domain_t found in upower_soc_defs.h. 650 * @rail: the pmic regulator number for the target domain. 651 * @stage: DVA adjust stage 652 * refer to upower_defs.h "DVA adjust stage" 653 * @target_freq: the target adjust frequency, accurate to MHz 654 * 655 * refer to upower_defs.h structure definition upwr_pwm_freq_msg 656 * 657 * @callb: response callback pointer; NULL if no callback needed. 658 * 659 * The DVA algorithm is broken down into two phases. 660 * The first phase uses a look up table to get a safe operating voltage 661 * for the requested frequency. 662 * This voltage is guaranteed to work over process and temperature. 663 * 664 * The second step of the second phase is to measure the temperature 665 * using the uPower Temperature Sensor module. 666 * This is accomplished by doing a binary search of the TSEL bit field 667 * in the Temperature Measurement Register (TMR). 668 * The search is repeated until the THIGH bit fields in the same register change value. 669 * There are 3 temperature sensors in 8ULP (APD, AVD, and RTD). 670 * 671 * 672 * The second phase is the fine adjust of the voltage. 673 * This stage is entered only when the new frequency requested 674 * by application was already set as well as the voltage for that frequency. 675 * The first step of the fine adjust is to find what is the current margins 676 * for the monitored critical paths, or, in other words, 677 * how many delay cells will be necessary to generate a setup-timing violation. 678 * The function informs uPower that the given domain frequency has changed or 679 * will change to the given value. uPower firmware will then adjust voltage and 680 * bias to cope with the new frequency (if decreasing) or prepare for it 681 * (if increasing). The function must be called after decreasing the frequency, 682 * and before increasing it. The actual increase in frequency must not occur 683 * before the service returns its response. 684 * 685 * So, for increase clock frequency case, user need to call this API twice, 686 * the first stage gross adjust and the second stage fine adjust. 687 * 688 * for reduce clock frequency case, user can only call this API once, 689 * full stage (combine gross stage and fine adjust) 690 * 691 * The request is executed if arguments are within range. 692 * 693 * A callback can be optionally registered, and will be called upon the arrival 694 * of the request response from the uPower firmware, telling if it succeeded 695 * or not. 696 * 697 * A callback may not be registered (NULL pointer), in which case polling has 698 * to be used to check the response, by calling upwr_req_status or 699 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 700 * 701 * Context: no sleep, no locks taken/released. 702 * Return: 0 if ok, 703 * -1 if service group is busy, 704 * -3 if called in an invalid API state 705 * Note that this is not the error response from the request itself: 706 * it only tells if the request was successfully sent to the uPower. 707 */ 708 int upwr_pwm_freq_setup(soc_domain_t domain, uint32_t rail, uint32_t stage, 709 uint32_t target_freq, upwr_callb callb); 710 711 /** 712 * upwr_pwm_power_on()- Powers on (not off) one or more switches and ROM/RAMs. 713 * @swton: pointer to an array of words that tells which power switches to 714 * turn on. Each word in the array has 1 bit for each switch. 715 * A bit=1 means the respective switch must be turned on, 716 * bit = 0 means it will stay unchanged (on or off). 717 * The pointer may be set to NULL, in which case no switch will be changed, 718 * unless a memory that it feeds must be turned on. 719 * WARNING: swton must not point to the first shared memory address. 720 * @memon: pointer to an array of words that tells which memories to turn on. 721 * Each word in the array has 1 bit for each switch. 722 * A bit=1 means the respective memory must be turned on, both array and 723 * periphery logic; 724 * bit = 0 means it will stay unchanged (on or off). 725 * The pointer may be set to NULL, in which case no memory will be changed. 726 * WARNING: memon must not point to the first shared memory address. 727 * @callb: pointer to the callback called when configurations are applyed. 728 * NULL if no callback is required. 729 * 730 * The function requests uPower to turn on the PMC and memory array/peripheral 731 * switches that control their power, as specified above. 732 * The request is executed if arguments are within range, with no protections 733 * regarding the adequate memory power state related to overall system state. 734 * 735 * If a memory is requested to turn on, but the power switch that feeds that 736 * memory is not, the power switch will be turned on anyway, if the pwron 737 * array is not provided (that is, if pwron is NULL). 738 * 739 * A callback can be optionally registered, and will be called upon the arrival 740 * of the request response from the uPower firmware, telling if it succeeded 741 * or not. 742 * 743 * A callback may not be registered (NULL pointer), in which case polling has 744 * to be used to check the response, by calling upwr_req_status or 745 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 746 * 747 * Callback or polling may return error if the service contends for a resource 748 * already being used by a power mode transition or an ongoing service in 749 * another domain. 750 * 751 * Context: no sleep, no locks taken/released. 752 * Return: 0 if ok, -1 if service group is busy, 753 * -2 if a pointer conversion to physical address failed, 754 * -3 if called in an invalid API state. 755 * Note that this is not the error response from the request itself: 756 * it only tells if the request was successfully sent to the uPower. 757 */ 758 int upwr_pwm_power_on(const uint32_t swton[], const uint32_t memon[], 759 upwr_callb callb); 760 761 /** 762 * upwr_pwm_power_off()- Powers off (not on) one or more switches and ROM/RAMs. 763 * @swtoff: pointer to an array of words that tells which power switches to 764 * turn off. Each word in the array has 1 bit for each switch. 765 * A bit=1 means the respective switch must be turned off, 766 * bit = 0 means it will stay unchanged (on or off). 767 * The pointer may be set to NULL, in which case no switch will be changed. 768 * WARNING: swtoff must not point to the first shared memory address. 769 * @memoff: pointer to an array of words that tells which memories to turn off. 770 * Each word in the array has 1 bit for each switch. 771 * A bit=1 means the respective memory must be turned off, both array and 772 * periphery logic; 773 * bit = 0 means it will stay unchanged (on or off). 774 * The pointer may be set to NULL, in which case no memory will be changed, 775 * but notice it may be turned off if the switch that feeds it is powered off. 776 * WARNING: memoff must not point to the first shared memory address. 777 * @callb: pointer to the callback called when configurations are applyed. 778 * NULL if no callback is required. 779 * 780 * The function requests uPower to turn off the PMC and memory array/peripheral 781 * switches that control their power, as specified above. 782 * The request is executed if arguments are within range, with no protections 783 * regarding the adequate memory power state related to overall system state. 784 * 785 * A callback can be optionally registered, and will be called upon the arrival 786 * of the request response from the uPower firmware, telling if it succeeded 787 * or not. 788 * 789 * A callback may not be registered (NULL pointer), in which case polling has 790 * to be used to check the response, by calling upwr_req_status or 791 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 792 * 793 * Callback or polling may return error if the service contends for a resource 794 * already being used by a power mode transition or an ongoing service in 795 * another domain. 796 * 797 * Context: no sleep, no locks taken/released. 798 * Return: 0 if ok, -1 if service group is busy, 799 * -2 if a pointer conversion to physical address failed, 800 * -3 if called in an invalid API state. 801 * Note that this is not the error response from the request itself: 802 * it only tells if the request was successfully sent to the uPower. 803 */ 804 int upwr_pwm_power_off(const uint32_t swtoff[], const uint32_t memoff[], 805 upwr_callb callb); 806 807 /** 808 * upwr_pwm_mem_retain()- Configures one or more memory power switches to 809 * retain its contents, having the power array on, while its peripheral logic 810 * is turned off. 811 * @mem: pointer to an array of words that tells which memories to put in a 812 * retention state. Each word in the array has 1 bit for each memory. 813 * A bit=1 means the respective memory must be put in retention state, 814 * bit = 0 means it will stay unchanged (retention, fully on or off). 815 * @callb: pointer to the callback called when configurations are applyed. 816 * NULL if no callback is required. 817 * 818 * The function requests uPower to turn off the memory peripheral and leave 819 * its array on, as specified above. 820 * The request is executed if arguments are within range. 821 * 822 * A callback can be optionally registered, and will be called upon the arrival 823 * of the request response from the uPower firmware, telling if it succeeded 824 * or not. 825 * 826 * A callback may not be registered (NULL pointer), in which case polling has 827 * to be used to check the response, by calling upwr_req_status or 828 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 829 * 830 * Callback or polling may return error if the service contends for a resource 831 * already being used by a power mode transition or an ongoing service in 832 * another domain. 833 * 834 * Context: no sleep, no locks taken/released. 835 * Return: 0 if ok, -1 if service group is busy, 836 * -2 if a pointer conversion to physical address failed, 837 * -3 if called in an invalid API state. 838 * Note that this is not the error response from the request itself: 839 * it only tells if the request was successfully sent to the uPower. 840 */ 841 int upwr_pwm_mem_retain(const uint32_t mem[], upwr_callb callb); 842 843 /** 844 * upwr_pwm_chng_switch_mem() - Turns on/off power on one or more PMC switches 845 * and memories, including their array and peripheral logic. 846 * @swt: pointer to a list of PMC switches to be opened/closed. 847 * The list is structured as an array of struct upwr_switch_board_t 848 * (see upower_defs.h), each one containing a word for up to 32 switches, 849 * one per bit. A bit = 1 means switch closed, bit = 0 means switch open. 850 * struct upwr_switch_board_t also specifies a mask with 1 bit for each 851 * respective switch: mask bit = 1 means the open/close action is applied, 852 * mask bit = 0 means the switch stays unchanged. 853 * The pointer may be set to NULL, in which case no switch will be changed, 854 * unless a memory that it feeds must be turned on. 855 * WARNING: swt must not point to the first shared memory address. 856 * @mem: pointer to a list of switches to be turned on/off. 857 * The list is structured as an array of struct upwr_mem_switches_t 858 * (see upower_defs.h), each one containing 2 word for up to 32 switches, 859 * one per bit, one word for the RAM array power switch, other for the 860 * RAM peripheral logic power switch. A bit = 1 means switch closed, 861 * bit = 0 means switch open. 862 * struct upwr_mem_switches_t also specifies a mask with 1 bit for each 863 * respective switch: mask bit = 1 means the open/close action is applied, 864 * mask bit = 0 means the switch stays unchanged. 865 * The pointer may be set to NULL, in which case no memory switch will be 866 * changed, but notice it may be turned off if the switch that feeds it is 867 * powered off. 868 * WARNING: mem must not point to the first shared memory address. 869 * @callb: pointer to the callback called when the configurations are applied. 870 * NULL if no callback is required. 871 * 872 * The function requests uPower to change the PMC switches and/or memory power 873 * as specified above. 874 * The request is executed if arguments are within range, with no protections 875 * regarding the adequate switch combinations and overall system state. 876 * 877 * If a memory is requested to turn on, but the power switch that feeds that 878 * memory is not, the power switch will be turned on anyway, if the swt 879 * array is not provided (that is, if swt is NULL). 880 * 881 * A callback can be optionally registered, and will be called upon the arrival 882 * of the request response from the uPower firmware, telling if it succeeded 883 * or not. 884 * 885 * A callback may not be registered (NULL pointer), in which case polling has 886 * to be used to check the response, by calling upwr_req_status or 887 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 888 * 889 * Callback or polling may return error if the service contends for a resource 890 * already being used by a power mode transition or an ongoing service in 891 * another domain. 892 * 893 * Context: no sleep, no locks taken/released. 894 * Return: 0 if ok, -1 if service group is busy. 895 * -2 if a pointer conversion to physical address failed, 896 * -3 if called in an invalid API state. 897 * Note that this is not the error response from the request itself: 898 * it only tells if the request was successfully sent to the uPower. 899 */ 900 int upwr_pwm_chng_switch_mem(const struct upwr_switch_board_t swt[], 901 const struct upwr_mem_switches_t mem[], 902 upwr_callb callb); 903 904 /** 905 * upwr_pwm_pmode_config() - Configures a given power mode in a given domain. 906 * @domain: identifier of the domain to which the power mode belongs. 907 * Defined by SoC-dependent type soc_domain_t found in upower_soc_defs.h. 908 * @pmode: SoC-dependent power mode identifier defined by type abs_pwr_mode_t 909 * found in upower_soc_defs.h. 910 * @config: pointer to an SoC-dependent struct defining the power mode 911 * configuration, found in upower_soc_defs.h. 912 * @callb: pointer to the callback called when configurations are applied. 913 * NULL if no callback is required. 914 * 915 * The function requests uPower to change the power mode configuration as 916 * specified above. The request is executed if arguments are within range, 917 * and complies with SoC-dependent restrictions on value combinations. 918 * 919 * A callback can be optionally registered, and will be called upon the arrival 920 * of the request response from the uPower firmware, telling if it succeeded 921 * or not. 922 * 923 * A callback may not be registered (NULL pointer), in which case polling has 924 * to be used to check the response, by calling upwr_req_status or 925 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 926 * 927 * Context: no sleep, no locks taken/released. 928 * Return: 0 if ok, -1 if service group is busy, 929 * -2 if the pointer conversion to physical address failed, 930 * -3 if called in an invalid API state. 931 * Note that this is not the error response from the request itself: 932 * it only tells if the request was successfully sent to the uPower. 933 */ 934 int upwr_pwm_pmode_config(soc_domain_t domain, abs_pwr_mode_t pmode, 935 const void *config, upwr_callb callb); 936 937 938 939 /** 940 * upwr_pwm_reg_config() - Configures the uPower internal regulators. 941 * @config: pointer to the struct defining the regulator configuration; 942 * the struct upwr_reg_config_t is defined in the file upower_defs.h. 943 * @callb: pointer to the callback called when configurations are applied. 944 * NULL if no callback is required. 945 * 946 * The function requests uPower to change/define the configurations of the 947 * internal regulators. 948 * 949 * A callback can be optionally registered, and will be called upon the arrival 950 * of the request response from the uPower firmware, telling if it succeeded 951 * or not. 952 * 953 * A callback may not be registered (NULL pointer), in which case polling has 954 * to be used to check the response, by calling upwr_req_status or 955 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 956 * 957 * The service may fail with error UPWR_RESP_RESOURCE if a power mode transition 958 * or the same service (called from another domain) is executing simultaneously. 959 * This error should be interpreted as a "try later" response, as the service 960 * will succeed once those concurrent executions are done, and no other is 961 * started. 962 * 963 * Context: no sleep, no locks taken/released. 964 * Return: 0 if ok, -1 if service group is busy, 965 * -2 if the pointer conversion to physical address failed, 966 * -3 if called in an invalid API state. 967 * Note that this is not the error response from the request itself: 968 * it only tells if the request was successfully sent to the uPower. 969 */ 970 int upwr_pwm_reg_config(const struct upwr_reg_config_t *config, 971 upwr_callb callb); 972 973 /** 974 * upwr_pwm_chng_dom_bias() - Changes the domain bias. 975 * @bias: pointer to a domain bias configuration struct (see upower_soc_defs.h). 976 * @callb: pointer to the callback called when configurations are applied. 977 * NULL if no callback is required. 978 * 979 * The function requests uPower to change the domain bias configuration as 980 * specified above. The request is executed if arguments are within range, 981 * with no protections regarding the adequate value combinations and 982 * overall system state. 983 * 984 * A callback can be optionally registered, and will be called upon the arrival 985 * of the request response from the uPower firmware, telling if it succeeded 986 * or not. 987 * 988 * A callback may not be registered (NULL pointer), in which case polling has 989 * to be used to check the response, by calling upwr_req_status or 990 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 991 * 992 * Context: no sleep, no locks taken/released. 993 * Return: 0 if ok, -1 if service group is busy, 994 * -3 if called in an invalid API state. 995 * Note that this is not the error response from the request itself: 996 * it only tells if the request was successfully sent to the uPower. 997 */ 998 999 int upwr_pwm_chng_dom_bias(const struct upwr_dom_bias_cfg_t *bias, 1000 upwr_callb callb); 1001 1002 /** 1003 * upwr_pwm_chng_mem_bias()- Changes a ROM/RAM power bias. 1004 * @domain: identifier of the domain upon which the bias is applied. 1005 * Defined by SoC-dependent type soc_domain_t found in upower_soc_defs.h. 1006 * @bias: pointer to a memory bias configuration struct (see upower_soc_defs.h). 1007 * @callb: pointer to the callback called when configurations are applied. 1008 * NULL if no callback is required. 1009 * 1010 * The function requests uPower to change the memory bias configuration as 1011 * specified above. The request is executed if arguments are within range, 1012 * with no protections regarding the adequate value combinations and 1013 * overall system state. 1014 * 1015 * A callback can be optionally registered, and will be called upon the arrival 1016 * of the request response from the uPower firmware, telling if it succeeded 1017 * or not. 1018 * 1019 * A callback may not be registered (NULL pointer), in which case polling has 1020 * to be used to check the response, by calling upwr_req_status or 1021 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 1022 * 1023 * Context: no sleep, no locks taken/released. 1024 * Return: 0 if ok, -1 if service group is busy, 1025 * -3 if called in an invalid API state. 1026 * Note that this is not the error response from the request itself: 1027 * it only tells if the request was successfully sent to the uPower. 1028 */ 1029 1030 int upwr_pwm_chng_mem_bias(soc_domain_t domain, 1031 const struct upwr_mem_bias_cfg_t *bias, 1032 upwr_callb callb); 1033 1034 /**--------------------------------------------------------------- 1035 * VOLTAGE MANAGEMENT SERVICE GROUP 1036 */ 1037 1038 /** 1039 * upwr_vtm_pmic_cold_reset() -request cold reset the pmic. 1040 * pmic will power cycle all the regulators 1041 * @callb: response callback pointer; NULL if no callback needed. 1042 * 1043 * The function requests uPower to cold reset the pmic. 1044 * The request is executed if arguments are within range, with no protections 1045 * regarding the adequate voltage value for the given domain process, 1046 * temperature and frequency. 1047 * 1048 * A callback can be optionally registered, and will be called upon the arrival 1049 * of the request response from the uPower firmware, telling if it succeeded 1050 * or not. 1051 * 1052 * A callback may not be registered (NULL pointer), in which case polling has 1053 * to be used to check the response, by calling upwr_req_status or 1054 * upwr_poll_req_status, using UPWR_SG_VOLTM as the service group argument. 1055 * 1056 * Context: no sleep, no locks taken/released. 1057 * Return: 0 if ok, 1058 * -1 if service group is busy, 1059 * -3 if called in an invalid API state 1060 * Note that this is not the error response from the request itself: 1061 * it only tells if the request was successfully sent to the uPower. 1062 */ 1063 int upwr_vtm_pmic_cold_reset(upwr_callb callb); 1064 1065 /** 1066 * upwr_vtm_set_pmic_mode() -request uPower set pmic mode 1067 * @pmic_mode: the target mode need to be set 1068 * @callb: response callback pointer; NULL if no callback needed. 1069 * 1070 * The function requests uPower to set pmic mode 1071 * The request is executed if arguments are within range, with no protections 1072 * regarding the adequate voltage value for the given domain process, 1073 * temperature and frequency. 1074 * 1075 * A callback can be optionally registered, and will be called upon the arrival 1076 * of the request response from the uPower firmware, telling if it succeeded 1077 * or not. 1078 * 1079 * A callback may not be registered (NULL pointer), in which case polling has 1080 * to be used to check the response, by calling upwr_req_status or 1081 * upwr_poll_req_status, using UPWR_SG_VOLTM as the service group argument. 1082 * 1083 * Context: no sleep, no locks taken/released. 1084 * Return: 0 if ok, 1085 * -1 if service group is busy, 1086 * -3 if called in an invalid API state 1087 * Note that this is not the error response from the request itself: 1088 * it only tells if the request was successfully sent to the uPower. 1089 */ 1090 int upwr_vtm_set_pmic_mode(uint32_t pmic_mode, upwr_callb callb); 1091 1092 /** 1093 * upwr_vtm_chng_pmic_voltage() - Changes the voltage of a given rail. 1094 * @rail: pmic rail id. 1095 * @volt: the target voltage of the given rail, accurate to uV 1096 * If pass volt value 0, means that power off this rail. 1097 * @callb: response callback pointer; NULL if no callback needed. 1098 * 1099 * The function requests uPower to change the voltage of the given rail. 1100 * The request is executed if arguments are within range, with no protections 1101 * regarding the adequate voltage value for the given domain process, 1102 * temperature and frequency. 1103 * 1104 * A callback can be optionally registered, and will be called upon the arrival 1105 * of the request response from the uPower firmware, telling if it succeeded 1106 * or not. 1107 * 1108 * A callback may not be registered (NULL pointer), in which case polling has 1109 * to be used to check the response, by calling upwr_req_status or 1110 * upwr_poll_req_status, using UPWR_SG_VOLTM as the service group argument. 1111 * 1112 * Context: no sleep, no locks taken/released. 1113 * Return: 0 if ok, 1114 * -1 if service group is busy, 1115 * -3 if called in an invalid API state 1116 * Note that this is not the error response from the request itself: 1117 * it only tells if the request was successfully sent to the uPower. 1118 */ 1119 int upwr_vtm_chng_pmic_voltage(uint32_t rail, uint32_t volt, upwr_callb callb); 1120 1121 /** 1122 * upwr_vtm_get_pmic_voltage() - Get the voltage of a given ral. 1123 * @rail: pmic rail id. 1124 * @callb: response callback pointer; NULL if no callback needed. 1125 * (polling used instead) 1126 * 1127 * The function requests uPower to get the voltage of the given rail. 1128 * The request is executed if arguments are within range, with no protections 1129 * regarding the adequate voltage value for the given domain process, 1130 * temperature and frequency. 1131 * 1132 * A callback can be optionally registered, and will be called upon the arrival 1133 * of the request response from the uPower firmware, telling if it succeeded 1134 * or not. 1135 * 1136 * A callback may not be registered (NULL pointer), in which case polling has 1137 * to be used to check the response, by calling upwr_req_status or 1138 * upwr_poll_req_status, using UPWR_SG_VOLTM as the service group argument. 1139 * 1140 * The voltage data read from uPower via 1141 * the callback argument ret, or written to the variable pointed by retptr, 1142 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 1143 * ret (or *retptr) also returns the data written on writes. 1144 * 1145 * Context: no sleep, no locks taken/released. 1146 * Return: 0 if ok, 1147 * -1 if service group is busy, 1148 * -3 if called in an invalid API state 1149 * Note that this is not the error response from the request itself: 1150 * it only tells if the request was successfully sent to the uPower. 1151 */ 1152 int upwr_vtm_get_pmic_voltage(uint32_t rail, upwr_callb callb); 1153 1154 1155 /** 1156 * upwr_vtm_power_measure() - request uPower to measure power consumption 1157 * @ssel: This field determines which power switches will have their currents 1158 * sampled to be accounted for a 1159 * current/power measurement. Support 0~7 1160 1161 * SSEL bit # Power Switch 1162 * 0 M33 core complex/platform/peripherals 1163 * 1 Fusion Core and Peripherals 1164 * 2 A35[0] core complex 1165 * 3 A35[1] core complex 1166 * 4 3DGPU 1167 * 5 HiFi4 1168 * 6 DDR Controller (PHY and PLL NOT included) 1169 * 7 PXP, EPDC 1170 * 1171 * @callb: response callback pointer; NULL if no callback needed. 1172 * (polling used instead) 1173 * 1174 * The function requests uPower to measure power consumption 1175 * The request is executed if arguments are within range, with no protections 1176 * regarding the adequate voltage value for the given domain process, 1177 * temperature and frequency. 1178 * 1179 * A callback can be optionally registered, and will be called upon the arrival 1180 * of the request response from the uPower firmware, telling if it succeeded 1181 * or not. 1182 * 1183 * A callback may not be registered (NULL pointer), in which case polling has 1184 * to be used to check the response, by calling upwr_req_status or 1185 * upwr_poll_req_status, using UPWR_SG_VOLTM as the service group argument. 1186 * 1187 * The power consumption data read from uPower via 1188 * the callback argument ret, or written to the variable pointed by retptr, 1189 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 1190 * ret (or *retptr) also returns the data written on writes. 1191 * upower fw needs support cocurrent request from M33 and A35. 1192 * 1193 * Accurate to uA 1194 * 1195 * Context: no sleep, no locks taken/released. 1196 * Return: 0 if ok, 1197 * -1 if service group is busy, 1198 * -3 if called in an invalid API state 1199 * Note that this is not the error response from the request itself: 1200 * it only tells if the request was successfully sent to the uPower. 1201 */ 1202 int upwr_vtm_power_measure(uint32_t ssel, upwr_callb callb); 1203 1204 /** 1205 * upwr_vtm_vmeter_measure() - request uPower to measure voltage 1206 * @vdetsel: Voltage Detector Selector, support 0~3 1207 * 00b - RTD sense point 1208 * 01b - LDO output 1209 * 10b - APD domain sense point 1210 * 11b - AVD domain sense point 1211 * Refer to upower_defs.h 1212 * @callb: response callback pointer; NULL if no callback needed. 1213 * (polling used instead) 1214 * 1215 * The function requests uPower to use vmeter to measure voltage 1216 * The request is executed if arguments are within range, with no protections 1217 * regarding the adequate voltage value for the given domain process, 1218 * temperature and frequency. 1219 * 1220 * A callback can be optionally registered, and will be called upon the arrival 1221 * of the request response from the uPower firmware, telling if it succeeded 1222 * or not. 1223 * 1224 * A callback may not be registered (NULL pointer), in which case polling has 1225 * to be used to check the response, by calling upwr_req_status or 1226 * upwr_poll_req_status, using UPWR_SG_VOLTM as the service group argument. 1227 * 1228 * The voltage data read from uPower via 1229 * the callback argument ret, or written to the variable pointed by retptr, 1230 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 1231 * ret (or *retptr) also returns the data written on writes. 1232 * upower fw needs support cocurrent request from M33 and A35. 1233 * 1234 * Refer to RM COREREGVL (Core Regulator Voltage Level) 1235 * uPower return VDETLVL to user, user can calculate the real voltage: 1236 * 1237 * 0b000000(0x00) - 0.595833V 1238 * 0b100110(0x26) - 1.007498V 1239 * <value> - 0.595833V + <value>x10.8333mV 1240 * 0b110010(0x32) - 1.138V 1241 * 1242 * Context: no sleep, no locks taken/released. 1243 * Return: 0 if ok, 1244 * -1 if service group is busy, 1245 * -3 if called in an invalid API state 1246 * Note that this is not the error response from the request itself: 1247 * it only tells if the request was successfully sent to the uPower. 1248 */ 1249 int upwr_vtm_vmeter_measure(uint32_t vdetsel, upwr_callb callb); 1250 1251 /** 1252 * upwr_vtm_pmic_config() - Configures the SoC PMIC (Power Management IC). 1253 * @config: pointer to a PMIC-dependent struct defining the PMIC configuration. 1254 * @size: size of the struct pointed by config, in bytes. 1255 * @callb: pointer to the callback called when configurations are applied. 1256 * NULL if no callback is required. 1257 * 1258 * The function requests uPower to change/define the PMIC configuration. 1259 * 1260 * A callback can be optionally registered, and will be called upon the arrival 1261 * of the request response from the uPower firmware, telling if it succeeded 1262 * or not. 1263 * 1264 * A callback may not be registered (NULL pointer), in which case polling has 1265 * to be used to check the response, by calling upwr_req_status or 1266 * upwr_poll_req_status, using UPWR_SG_PWRMGMT as the service group argument. 1267 * 1268 * Context: no sleep, no locks taken/released. 1269 * Return: 0 if ok, -1 if service group is busy, 1270 * -2 if the pointer conversion to physical address failed, 1271 * -3 if called in an invalid API state. 1272 * Note that this is not the error response from the request itself: 1273 * it only tells if the request was successfully sent to the uPower. 1274 */ 1275 int upwr_vtm_pmic_config(const void *config, uint32_t size, upwr_callb callb); 1276 1277 /**--------------------------------------------------------------- 1278 * TEMPERATURE MANAGEMENT SERVICE GROUP 1279 */ 1280 1281 /** 1282 * upwr_tpm_get_temperature() - request uPower to get temperature of one temperature sensor 1283 * @sensor_id: temperature sensor ID, support 0~2 1284 * @callb: response callback pointer; NULL if no callback needed. 1285 * (polling used instead) 1286 * 1287 * The function requests uPower to measure temperature 1288 * The request is executed if arguments are within range, with no protections 1289 * regarding the adequate voltage value for the given domain process, 1290 * temperature and frequency. 1291 * 1292 * A callback can be optionally registered, and will be called upon the arrival 1293 * of the request response from the uPower firmware, telling if it succeeded 1294 * or not. 1295 * 1296 * A callback may not be registered (NULL pointer), in which case polling has 1297 * to be used to check the response, by calling upwr_req_status or 1298 * upwr_poll_req_status, using UPWR_SG_TEMPM as the service group argument. 1299 * 1300 * The temperature data read from uPower via 1301 * the callback argument ret, or written to the variable pointed by retptr, 1302 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 1303 * ret (or *retptr) also returns the data written on writes. 1304 * 1305 * uPower return TSEL to the caller (M33 or A35), caller calculate the real temperature 1306 * Tsh = 0.000002673049*TSEL[7:0]^3 + 0.0003734262*TSEL[7:0]^2 + 1307 0.4487042*TSEL[7:0] - 46.98694 1308 * 1309 * upower fw needs support cocurrent request from M33 and A35. 1310 * 1311 * Context: no sleep, no locks taken/released. 1312 * Return: 0 if ok, 1313 * -1 if service group is busy, 1314 * -3 if called in an invalid API state 1315 * Note that this is not the error response from the request itself: 1316 * it only tells if the request was successfully sent to the uPower. 1317 */ 1318 int upwr_tpm_get_temperature(uint32_t sensor_id, upwr_callb callb); 1319 1320 /**--------------------------------------------------------------- 1321 * DELAY MANAGEMENT SERVICE GROUP 1322 */ 1323 1324 /** 1325 * upwr_dlm_get_delay_margin() - request uPower to get delay margin 1326 * @path: The critical path 1327 * @index: Use whitch delay meter 1328 * @callb: response callback pointer; NULL if no callback needed. 1329 * (polling used instead) 1330 * 1331 * The function requests uPower to get delay margin 1332 * The request is executed if arguments are within range, with no protections 1333 * regarding the adequate voltage value for the given domain process, 1334 * temperature and frequency. 1335 * 1336 * A callback can be optionally registered, and will be called upon the arrival 1337 * of the request response from the uPower firmware, telling if it succeeded 1338 * or not. 1339 * 1340 * A callback may not be registered (NULL pointer), in which case polling has 1341 * to be used to check the response, by calling upwr_req_status or 1342 * upwr_poll_req_status, using UPWR_SG_DELAYM as the service group argument. 1343 * 1344 * The delay margin data read from uPower via 1345 * the callback argument ret, or written to the variable pointed by retptr, 1346 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 1347 * ret (or *retptr) also returns the data written on writes. 1348 * upower fw needs support cocurrent request from M33 and A35. 1349 * 1350 * Context: no sleep, no locks taken/released. 1351 * Return: 0 if ok, 1352 * -1 if service group is busy, 1353 * -3 if called in an invalid API state 1354 * Note that this is not the error response from the request itself: 1355 * it only tells if the request was successfully sent to the uPower. 1356 */ 1357 int upwr_dlm_get_delay_margin(uint32_t path, uint32_t index, upwr_callb callb); 1358 1359 /** 1360 * upwr_dlm_set_delay_margin() - request uPower to set delay margin 1361 * @path: The critical path 1362 * @index: Use whitch delay meter 1363 * @delay_margin: the value of delay margin 1364 * @callb: response callback pointer; NULL if no callback needed. 1365 * (polling used instead) 1366 * 1367 * The function requests uPower to set delay margin 1368 * The request is executed if arguments are within range, with no protections 1369 * regarding the adequate voltage value for the given domain process, 1370 * temperature and frequency. 1371 * 1372 * A callback can be optionally registered, and will be called upon the arrival 1373 * of the request response from the uPower firmware, telling if it succeeded 1374 * or not. 1375 * 1376 * A callback may not be registered (NULL pointer), in which case polling has 1377 * to be used to check the response, by calling upwr_req_status or 1378 * upwr_poll_req_status, using UPWR_SG_DELAYM as the service group argument. 1379 * 1380 * The result of the corresponding critical path, failed or not read from uPower via 1381 * the callback argument ret, or written to the variable pointed by retptr, 1382 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 1383 * ret (or *retptr) also returns the data written on writes. 1384 * upower fw needs support cocurrent request from M33 and A35. 1385 * 1386 * Context: no sleep, no locks taken/released. 1387 * Return: 0 if ok, 1388 * -1 if service group is busy, 1389 * -3 if called in an invalid API state 1390 * Note that this is not the error response from the request itself: 1391 * it only tells if the request was successfully sent to the uPower. 1392 */ 1393 int upwr_dlm_set_delay_margin(uint32_t path, uint32_t index, uint32_t delay_margin, upwr_callb callb); 1394 1395 /** 1396 * upwr_dlm_process_monitor() - request uPower to do process monitor 1397 * @chain_sel: Chain Cell Type Selection 1398 * Select the chain to be used for the clock signal generation. 1399 * Support two types chain cell, 0~1 1400 0b - P4 type delay cells selected 1401 1b - P16 type delay cells selected 1402 * @callb: response callback pointer; NULL if no callback needed. 1403 * (polling used instead) 1404 * 1405 * The function requests uPower to do process monitor 1406 * The request is executed if arguments are within range, with no protections 1407 * regarding the adequate voltage value for the given domain process, 1408 * temperature and frequency. 1409 * 1410 * A callback can be optionally registered, and will be called upon the arrival 1411 * of the request response from the uPower firmware, telling if it succeeded 1412 * or not. 1413 * 1414 * A callback may not be registered (NULL pointer), in which case polling has 1415 * to be used to check the response, by calling upwr_req_status or 1416 * upwr_poll_req_status, using UPWR_SG_DELAYM as the service group argument. 1417 * 1418 * The result of process monitor, failed or not read from uPower via 1419 * the callback argument ret, or written to the variable pointed by retptr, 1420 * if polling is used (calls upwr_req_status or upwr_poll_req_status). 1421 * ret (or *retptr) also returns the data written on writes. 1422 * upower fw needs support cocurrent request from M33 and A35. 1423 * 1424 * Context: no sleep, no locks taken/released. 1425 * Return: 0 if ok, 1426 * -1 if service group is busy, 1427 * -3 if called in an invalid API state 1428 * Note that this is not the error response from the request itself: 1429 * it only tells if the request was successfully sent to the uPower. 1430 */ 1431 int upwr_dlm_process_monitor(uint32_t chain_sel, upwr_callb callb); 1432 1433 /**--------------------------------------------------------------- 1434 * DIAGNOSE SERVICE GROUP 1435 */ 1436 1437 /** 1438 * upwr_dgn_mode() - Sets the diagnostic mode. 1439 * @mode: diagnostic mode, which can be: 1440 * - UPWR_DGN_NONE: no diagnostic recorded 1441 * - UPWR_DGN_TRACE: warnings, errors, service, internal activity recorded 1442 * - UPWR_DGN_SRVREQ: warnings, errors, service activity recorded 1443 * - UPWR_DGN_WARN: warnings and errors recorded 1444 * - UPWR_DGN_ALL: trace, service, warnings, errors, task state recorded 1445 * - UPWR_DGN_ERROR: only errors recorded 1446 * - UPWR_DGN_ALL2ERR: record all until an error occurs, 1447 * freeze recording on error 1448 * - UPWR_DGN_ALL2HLT: record all until an error occurs, 1449 * executes an ebreak on error, which halts the core if enabled through 1450 * the debug interface 1451 * @callb: pointer to the callback called when mode is changed. 1452 * NULL if no callback is required. 1453 * 1454 * Context: no sleep, no locks taken/released. 1455 * Return: 0 if ok, 1456 * -1 if service group is busy, 1457 * -3 if called in an invalid API state 1458 */ 1459 int upwr_dgn_mode(upwr_dgn_mode_t mode, const upwr_callb callb); 1460 1461 /**--------------------------------------------------------------- 1462 * AUXILIARY CALLS 1463 */ 1464 1465 /** 1466 * upwr_rom_version() - informs the ROM firwmware version. 1467 * @vmajor: pointer to the variable to get the firmware major version number. 1468 * @vminor: pointer to the variable to get the firmware minor version number. 1469 * @vfixes: pointer to the variable to get the firmware fixes number. 1470 * 1471 * Context: no sleep, no locks taken/released. 1472 * Return: SoC id. 1473 */ 1474 uint32_t upwr_rom_version(uint32_t *vmajor, uint32_t *vminor, uint32_t *vfixes); 1475 1476 /** 1477 * upwr_ram_version() - informs the RAM firwmware version. 1478 * @vminor: pointer to the variable to get the firmware minor version number. 1479 * @vfixes: pointer to the variable to get the firmware fixes number. 1480 * 1481 * The 3 values returned are 0 if no RAM firmwmare was loaded and initialized. 1482 * 1483 * Context: no sleep, no locks taken/released. 1484 * Return: firmware major version number. 1485 */ 1486 uint32_t upwr_ram_version(uint32_t *vminor, uint32_t *vfixes); 1487 1488 /** 1489 * upwr_req_status() - tells the status of the service group request, and 1490 * returns a request return value, if any. 1491 * @sg: service group of the request 1492 * @sgfptr: pointer to the variable that will hold the function id of 1493 * the last request completed; can be NULL, in which case it is not used. 1494 * @errptr: pointer to the variable that will hold the error code; 1495 * can be NULL, in which case it is not used. 1496 * @retptr: pointer to the variable that will hold the value returned 1497 * by the last request completed (invalid if the last request completed didn't 1498 * return any value); can be NULL, in which case it is not used. 1499 * Note that a request may return a value even if service error is returned 1500 * (*errptr != UPWR_RESP_OK): that is dependent on the specific service. 1501 * 1502 * This call can be used in a poll loop of a service request completion in case 1503 * a callback was not registered. 1504 * 1505 * Context: no sleep, no locks taken/released. 1506 * Return: service request status: succeeded, failed, or ongoing (busy) 1507 */ 1508 1509 /* service request status */ 1510 typedef enum { 1511 UPWR_REQ_OK, /* request succeeded */ 1512 UPWR_REQ_ERR, /* request failed */ 1513 UPWR_REQ_BUSY /* request execution ongoing */ 1514 } upwr_req_status_t; 1515 1516 upwr_req_status_t upwr_req_status(upwr_sg_t sg, 1517 uint32_t *sgfptr, 1518 upwr_resp_t *errptr, 1519 int *retptr); 1520 1521 /** 1522 * upwr_poll_req_status() - polls the status of the service group request, and 1523 * returns a request return value, if any. 1524 * @sg: service group of the request 1525 * @sgfptr: pointer to the variable that will hold the function id of 1526 * the last request completed; can be NULL, in which case it is not used. 1527 * @errptr: pointer to the variable that will hold the error code; 1528 * can be NULL, in which case it is not used. 1529 * @retptr: pointer to the variable that will hold the value returned 1530 * by the last request completed (invalid if the last request completed didn't 1531 * return any value); can be NULL, in which case it is not used. 1532 * Note that a request may return a value even if service error is returned 1533 * (*errptr != UPWR_RESP_OK): that is dependent on the specific service. 1534 * @attempts: maximum number of polling attempts; if attempts > 0 and is 1535 * reached with no service response received, upwr_poll_req_status returns 1536 * UPWR_REQ_BUSY and variables pointed by sgfptr, retptr and errptr are not 1537 * updated; if attempts = 0, upwr_poll_req_status waits "forever". 1538 * 1539 * This call can be used to poll a service request completion in case a 1540 * callback was not registered. 1541 * 1542 * Context: no sleep, no locks taken/released. 1543 * Return: service request status: succeeded, failed, or ongoing (busy) 1544 */ 1545 upwr_req_status_t upwr_poll_req_status(upwr_sg_t sg, 1546 uint32_t *sgfptr, 1547 upwr_resp_t *errptr, 1548 int *retptr, 1549 uint32_t attempts); 1550 1551 /** 1552 * upwr_alarm_code() - returns the alarm code of the last alarm occurrence. 1553 * 1554 * The value returned is not meaningful if no alarm was issued by uPower. 1555 * 1556 * Context: no sleep, no locks taken/released. 1557 * Return: alarm code, as defined by the type upwr_alarm_t in upwr_soc_defines.h 1558 */ 1559 upwr_alarm_t upwr_alarm_code(void); 1560 1561 /**--------------------------------------------------------------- 1562 * TRANSMIT/RECEIVE PRIMITIVES 1563 * --------------------------------------------------------------- 1564 */ 1565 1566 typedef void (*UPWR_TX_CALLB_FUNC_T)(void); 1567 typedef void (*UPWR_RX_CALLB_FUNC_T)(void); 1568 1569 /** 1570 * upwr_tx() - queues a message for transmission. 1571 * @msg : pointer to the message sent. 1572 * @size: message size in 32-bit words 1573 * @callback: pointer to a function to be called when transmission done; 1574 * can be NULL, in which case no callback is done. 1575 * 1576 * This is an auxiliary function used by the rest of the API calls. 1577 * It is normally not called by the driver code, unless maybe for test purposes. 1578 * 1579 * Context: no sleep, no locks taken/released. 1580 * Return: number of vacant positions left in the transmission queue, or 1581 * -1 if the queue was already full when upwr_tx was called, or 1582 * -2 if any argument is invalid (like size off-range) 1583 */ 1584 int upwr_tx(const uint32_t *msg, unsigned int size, 1585 UPWR_TX_CALLB_FUNC_T callback); 1586 1587 /** 1588 * upwr_rx() - unqueues a received message from the reception queue. 1589 * @msg: pointer to the message destination buffer. 1590 * @size: pointer to variable to hold message size in 32-bit words. 1591 * 1592 * This is an auxiliary function used by the rest of the API calls. 1593 * It is normally not called by the driver code, unless maybe for test purposes. 1594 * 1595 * Context: no sleep, no locks taken/released. 1596 * Return: number of messages remaining in the reception queue, or 1597 * -1 if the queue was already empty when upwr_rx was called, or 1598 * -2 if any argument is invalid (like mu off-range) 1599 */ 1600 int upwr_rx(char *msg, unsigned int *size); 1601 1602 /** 1603 * upwr_rx_callback() - sets up a callback for a message receiving event. 1604 * @callback: pointer to a function to be called when a message arrives; 1605 * can be NULL, in which case no callback is done. 1606 * 1607 * This is an auxiliary function used by the rest of the API calls. 1608 * It is normally not called by the driver code, unless maybe for test purposes. 1609 * 1610 * Context: no sleep, no locks taken/released. 1611 * Return: 0 if ok; -2 if any argument is invalid (mu off-range). 1612 */ 1613 int upwr_rx_callback(UPWR_RX_CALLB_FUNC_T callback); 1614 1615 /** 1616 * msg_copy() - copies a message. 1617 * @dest: pointer to the destination message. 1618 * @src : pointer to the source message. 1619 * @size: message size in words. 1620 * 1621 * This is an auxiliary function used by the rest of the API calls. 1622 * It is normally not called by the driver code, unless maybe for test purposes. 1623 * 1624 * Context: no sleep, no locks taken/released. 1625 * Return: none (void) 1626 */ 1627 void msg_copy(char *dest, char *src, unsigned int size); 1628 1629 #endif /* UPWR_API_H */ 1630