Re: [PATCH v3 1/7] qga: guest-get-fsinfo: add optional 'total-bytes-root' field

[Andrey Drobyshev]

On 3/15/24 15:44, Markus Armbruster wrote:
> [?? ??????? ????????? ?????? ?? armbru@redhat.com. ???????, ?????? ??? ?????, 
> ?? ?????? https://aka.ms/LearnAboutSenderIdentification ]
> 
> Andrey Drobyshev <andrey.drobyshev@virtuozzo.com> writes:
> 
>> Since the commit 25b5ff1a86 ("qga: add mountpoint usage info to
>> GuestFilesystemInfo") we have 2 values reported in guest-get-fsinfo:
>> used = (f_blocks - f_bfree), total = (f_blocks - f_bfree + f_bavail) as
>> returned by statvfs(3).  While on Windows guests that's all we can get
>> with GetDiskFreeSpaceExA(), on POSIX guests we might also be interested in
>> total file system size, as it's visible for root user.  Let's add an
>> optional field 'total-bytes-root' to GuestFilesystemInfo struct, which'd
>> only be reported on POSIX and represent f_blocks value as returned by
>> statvfs(3).
>>
>> While here, let's document better where those values come from in both
>> POSIX and Windows.
>>
>> Signed-off-by: Andrey Drobyshev <andrey.drobyshev@virtuozzo.com>
> 
> [...]
> 
>> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
>> index b8efe31897..093a5ab602 100644
>> --- a/qga/qapi-schema.json
>> +++ b/qga/qapi-schema.json
>> @@ -1031,8 +1031,18 @@
>>  # @type: file system type string
>>  #
>>  # @used-bytes: file system used bytes (since 3.0)
>> +#     * POSIX: (f_blocks - f_bfree) * f_frsize, as returned by statvfs(3)
>> +#     * Windows: (TotalNumberOfBytes - TotalNumberOfFreeBytes), as returned
>> +#       by GetDiskFreeSpaceEx()
>>  #
>>  # @total-bytes: non-root file system total bytes (since 3.0)
>> +#     * POSIX: (f_blocks - f_bfree + f_bavail) * f_frsize, as returned by
>> +#       statvfs(3)
>> +#     * Windows: TotalNumberOfBytes, as returned by GetDiskFreeSpaceEx()
>> +#
>> +# @total-bytes-root: total file system size in bytes (as visible for a
>> +#     priviledged user) (since 8.3)
> 
> privileged
> 
>> +#     * POSIX only: (f_blocks * f_frsize), returned by statvfs(3)
>>  #
>>  # @disk: an array of disk hardware information that the volume lies
>>  #     on, which may be empty if the disk type is not supported
>> @@ -1042,7 +1052,7 @@
>>  { 'struct': 'GuestFilesystemInfo',
>>    'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str',
>>             '*used-bytes': 'uint64', '*total-bytes': 'uint64',
>> -           'disk': ['GuestDiskAddress']} }
>> +           '*total-bytes-root': 'uint64', 'disk': ['GuestDiskAddress']} }
>>
>>  ##
>>  # @guest-get-fsinfo:
> 
> Fails to build the manual:
> 
>     qga/qapi-schema.json:1019:Unexpected indentation.
> 
> To fix, add blank lines before the lists, like this:
> 
>    # @used-bytes: file system used bytes (since 3.0)
>    #
>    #     * POSIX: (f_blocks - f_bfree) * f_frsize, as returned by
>    #       statvfs(3)
>    #     * Windows: (TotalNumberOfBytes - TotalNumberOfFreeBytes), as
>    #       returned by GetDiskFreeSpaceEx()
>    #
>    # @total-bytes: non-root file system total bytes (since 3.0)
>    #
>    #     * POSIX: (f_blocks - f_bfree + f_bavail) * f_frsize, as returned by
>    #       statvfs(3)
>    #     * Windows: TotalNumberOfBytes, as returned by GetDiskFreeSpaceEx()
>    #
>    # @total-bytes-root: total file system size in bytes (as visible for a
>    #     privileged user) (since 8.3)
>    #
>    #     * POSIX only: (f_blocks * f_frsize), returned by statvfs(3)
>    #
> 
> Yes, reST can be quite annoying.
> 

For some reason in my environment build doesn't fail and file
build/docs/qemu-ga-ref.7 is produced.  However lists aren't indeed
formatted properly.  I'll wait for other patches to be reviewed and fix
that in v4.  Thank you for noticing.