On 15.05.2025 15:02, Markus Armbruster wrote:
> Mario Fleischmann <mario.fleischm...@lauterbach.com> writes:
>
>> The target initialization API ensures that the requested and provided
>> MCD versions are compatible.
>>
>> * implement mcd_initialize_f and mcd_qry_error_info_f in mcdserver
>> * implement QMP stub functionality
>> * add QTest
>>
>> Thanks to the QMP integration in QTest, function arguments and results
>> can be (de)serialized automatically.
>>
>> Signed-off-by: Mario Fleischmann <mario.fleischm...@lauterbach.com>
>
> [...]
>
>> diff --git a/qapi/mcd.json b/qapi/mcd.json
>> index 701fd03..7b42a74 100644
>> --- a/qapi/mcd.json
>> +++ b/qapi/mcd.json
>> @@ -4,3 +4,186 @@
>> ##
>> # = Multi-Core Debug (MCD) API
>> ##
>> +
>> +
>> +##
>> +# == Definition of Structures
>> +##
>> +
>> +
>> +##
>> +# @MCDAPIVersion:
>> +#
>> +# Structure type containing the MCD API version information of the tool.
>> +#
>> +# @v-api-major: API major version.
>> +# @v-api-minor: API minor version.
>> +# @author: API name of the author of this MCD API version.
>> +#
>> +# Since: 9.1
>> +##
>> +{ 'struct': 'MCDAPIVersion',
>> + 'data': {
>> + 'v-api-major': 'uint16',
>> + 'v-api-minor': 'uint16',
>> + 'author': 'str' } }
>> +
>> +
>> +##
>> +# @MCDImplVersionInfo:
>> +#
>> +# Structure type containing the MCD API implementation information.
>> +#
>> +# @v-api: Implemented API version.
>> +# @v-imp-major: Major version number of this implementation.
>> +# @v-imp-minor: Minor version number of this implementation.
>> +# @v-imp-build: Build number of this implementation.
>> +# @vendor: Name of vendor of the implementation.
>> +# @date: String from __DATE__ macro at compile time.
>> +#
>> +# Since: 9.1
>> +##
>> +{ 'struct': 'MCDImplVersionInfo',
>> + 'data': {
>> + 'v-api' : 'MCDAPIVersion',
>> + 'v-imp-major': 'uint16',
>> + 'v-imp-minor': 'uint16',
>> + 'v-imp-build': 'uint16',
>> + 'vendor' : 'str',
>> + 'date' : 'str' } }
>> +
>> +
>> +##
>> +# @MCDErrorInfo:
>> +#
>> +# Structure type containing the error status and error event notification.
>> +#
>> +# @return-status: Return status from the last API call.
>> +# @error-code: Detailed error code from the last API call.
>> +# @error-events: Detailed event code from the last API call.
>> +# @error-str: Detailed error text string from the last API call.
>> +#
>> +# Since: 9.1
>> +##
>> +{ 'struct': 'MCDErrorInfo',
>> + 'data': {
>> + 'return-status': 'uint32',
>> + 'error-code' : 'uint32',
>> + 'error-events' : 'uint32',
>> + 'error-str' : 'str' }}
>> +
>> +
>> +##
>> +# == Target Initialization API
>> +##
>> +
>> +
>> +##
>> +# @MCDInitializeResult:
>> +#
>> +# Return value of @mcd-initialize.
>> +#
>> +# @return-status: Return code.
>> +#
>> +# @impl-info: Information about the QEMU build, its version and the version
>> of
>> +# the implemented MCD API.
>> +#
>> +# Since: 9.1
>> +##
>> +{ 'struct': 'MCDInitializeResult',
>> + 'data': {
>> + 'return-status': 'uint32',
>> + '*impl-info' : 'MCDImplVersionInfo' } }
>> +
>> +
>> +##
>> +# @mcd-initialize:
>> +#
>> +# Function initializing the interaction between a tool-side implementation
>> and
>> +# target-side implementation.
>> +#
>> +# @version-req: MCD API version as requested by an upper layer.
>> +#
>> +# Returns: @MCDInitializeResult
>> +#
>> +# Since: 9.1
>> +#
>> +# .. qmp-example::
>> +# :title: Check compatibility with MCD server
>> +#
>> +# -> { "execute": "mcd-initialize",
>> +# "arguments": { "version-req": { "v-api-major": 1,
>> +# "v-api-minor": 1,
>> +# "author": "" } } }
>> +# <- {
>> +# "return": {
>> +# "impl-info": {
>> +# "v-api": {
>> +# "v-api-minor": 1,
>> +# "v-api-major": 1,
>> +# "author": "QEMU Release"
>> +# },
>> +# "vendor": "QEMU",
>> +# "v-imp-minor": 2,
>> +# "v-imp-major": 9,
>> +# "v-imp-build": 0,
>> +# "date": "Dec 18 2024"
>> +# },
>> +# "return-status": 0
>> +# }
>> +# }
>> +##
>> +{ 'command': 'mcd-initialize',
>> + 'data': { 'version-req': 'MCDAPIVersion' },
>> + 'returns': 'MCDInitializeResult' }
>> +
>> +
>> +##
>> +# @mcd-exit:
>> +#
>> +# Function cleaning up all core and server connections from a tool.
>> +#
>> +# Since: 9.1
>> +##
>> +{ 'command': 'mcd-exit' }
>> +
>> +
>> +##
>> +# == Core Connection API
>> +##
>> +
>> +
>> +##
>> +# @mcd-qry-error-info:
>> +#
>> +# Function allowing the access to detailed error and/or event information
>> after
>> +# an API call.
>> +#
>> +# Returns: @MCDErrorInfo
>> +#
>> +# Since: 9.1
>> +#
>> +# .. qmp-example::
>> +# :title: Incompatible MCD versions
>> +#
>> +# -> { "execute": "mcd-initialize",
>> +# "arguments": { "version-req": { "v-api-major": 2,
>> +# "v-api-minor": 0,
>> +# "author": "" } } }
>> +# <- {
>> +# "return": {
>> +# "return-status": 3
>> +# }
>> +# }
>> +# -> { "execute": "mcd-qry-error-info" }
>> +# <- {
>> +# "return": {
>> +# "error-str": "incompatible versions",
>> +# "error-code": 3840,
>> +# "error-events": 0,
>> +# "return-status": 3
>> +# }
>> +# }
>> +##
>> +{ 'command': 'mcd-qry-error-info',
>> + 'returns': 'MCDErrorInfo' }
>
> You define some types under "Definition of Structures", and some
> elsewhere. How do you decide what goes where? Hmm, looks like you
> mirror mcd/mcd_api.h. Correct?
Generally, mcd/qapi-schema.json is intended to stay as close as possible
to mcd_api.h. However, there are a few exceptions.
If a function "MCDFunction" from the MCD API has multiple return values,
an additional QAPI struct with the naming scheme "MCDFunctionResult" is
introduced which will be returned by "MCDFunction".
Since this struct is intended to be used by only one function, it is
defined directly before that function.
If the type of an argument or return value cannot be serialized, most
often because it is a pointer, it is changed to a type which is able to
carry the same information. In most cases, an int carrying a unique
identifier suffices. Sometimes, an additional struct is required.
This struct can possibly be used by multiple functions, so I would
expect it in the "Definition of Structures" section.
