docs: def upgrade(refresh=False, **kwargs):
      '''
      Upgrade all packages to the latest possible version.
      When run in global zone, it updates also all non-global zones.
      In non-global zones upgrade is limited by dependency constrains linked to
      the version of pkg://solaris/entire.
  
      Returns a dictionary containing the changes:
  
      .. code-block:: python
  
          {'<package>':  {'old': '<old-version>',
                          'new': '<new-version>'}}
  
      When there is a failure, an explanation is also included in the error
      message, based on the return code of the ``pkg update`` command.
  
  
      CLI Example:
  
      .. code-block:: bash
  
          salt '*' pkg.upgrade
      '''
      if salt.utils.data.is_true(refresh):
          refresh_db()
  
      # Get a list of the packages before install so we can diff after to see
      # what got installed.
      old = list_pkgs()
  
      # Install or upgrade the package
      # If package is already installed
      cmd = ['pkg', 'update', '-v', '--accept']
      result = __salt__['cmd.run_all'](cmd,
                                       output_loglevel='trace',
                                       python_shell=False)
      __context__.pop('pkg.list_pkgs', None)
      new = list_pkgs()
      ret = salt.utils.data.compare_dicts(old, new)
  
      if result['retcode'] != 0:
          raise CommandExecutionError(
              'Problem encountered upgrading packages',
              info={'changes': ret,
                    'retcode': ips_pkg_return_values[result['retcode']],
                    'result': result}
          )
  
      return ret