motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-07 09:43:56 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

fw_cfg: move internal function call docs to header file

Browse source 
Move documentation for fw_cfg functions internal to qemufrom
docs/specs/fw_cfg.txt to the fw_cfg.h header file, next to
their prototype declarations, formatted as doc-comments.

NOTE: Documentation for fw_cfg_add_callback() is completely
dropped by this patch, as that function has been eliminated
by commit 023e3148.

Suggested-by: Peter Maydell <peter.maydell@linaro.org>
Cc: Laszlo Ersek <lersek@redhat.com>
Cc: Gerd Hoffmann <kraxel@redhat.com>
Cc: Marc Marí <markmb@redhat.com>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Gabriel Somlo <somlo@cmu.edu>
Reviewed-by: Laszlo Ersek <lersek@redhat.com>
Message-id: 1446733972-1602-2-git-send-email-somlo@cmu.edu
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
This commit is contained in:
Gabriel L. Somlo 2015-11-05 09:32:47 -05:00 • committed by Gerd Hoffmann
parent f05b42d3fd
commit 9c4a5c55f5
2 changed files with 130 additions and 84 deletions
Download patch file Download diff file Expand all files Collapse all files

85
docs/specs/fw_cfg.txt
View file

@ -192,90 +192,7 @@ To check the result, read the "control" field:
today due to implementation not being async,
but may in the future).
= Host-side API =
The following functions are available to the QEMU programmer for adding
data to a fw_cfg device during guest initialization (see fw_cfg.h for
each function's complete prototype):
== fw_cfg_add_bytes() ==
Given a selector key value, starting pointer, and size, create an item
as a raw "blob" of the given size, available by selecting the given key.
The data referenced by the starting pointer is only linked, NOT copied,
into the data structure of the fw_cfg device.
== fw_cfg_add_string() ==
Instead of a starting pointer and size, this function accepts a pointer
to a NUL-terminated ascii string, and inserts a newly allocated copy of
the string (including the NUL terminator) into the fw_cfg device data
structure.
== fw_cfg_add_iXX() ==
Insert an XX-bit item, where XX may be 16, 32, or 64. These functions
will convert a 16-, 32-, or 64-bit integer to little-endian, then add
a dynamically allocated copy of the appropriately sized item to fw_cfg
under the given selector key value.
== fw_cfg_modify_iXX() ==
Modify the value of an XX-bit item (where XX may be 16, 32, or 64).
Similarly to the corresponding fw_cfg_add_iXX() function set, convert
a 16-, 32-, or 64-bit integer to little endian, create a dynamically
allocated copy of the required size, and replace the existing item at
the given selector key value with the newly allocated one. The previous
item, assumed to have been allocated during an earlier call to
fw_cfg_add_iXX() or fw_cfg_modify_iXX() (of the same width XX), is freed
before the function returns.
== fw_cfg_add_file() ==
Given a filename (i.e., fw_cfg item name), starting pointer, and size,
create an item as a raw "blob" of the given size. Unlike fw_cfg_add_bytes()
above, the next available selector key (above 0x0020, FW_CFG_FILE_FIRST)
will be used, and a new entry will be added to the file directory structure
(at key 0x0019), containing the item name, blob size, and automatically
assigned selector key value. The data referenced by the starting pointer
is only linked, NOT copied, into the fw_cfg data structure.
== fw_cfg_add_file_callback() ==
Like fw_cfg_add_file(), but additionally sets pointers to a callback
function (and opaque argument), which will be executed host-side by
QEMU each time a byte is read by the guest from this particular item.
NOTE: The callback function is given the opaque argument set by
fw_cfg_add_file_callback(), but also the current data offset,
allowing it the option of only acting upon specific offset values
(e.g., 0, before the first data byte of the selected item is
returned to the guest).
== fw_cfg_modify_file() ==
Given a filename (i.e., fw_cfg item name), starting pointer, and size,
completely replace the configuration item referenced by the given item
name with the new given blob. If an existing blob is found, its
callback information is removed, and a pointer to the old data is
returned to allow the caller to free it, helping avoid memory leaks.
If a configuration item does not already exist under the given item
name, a new item will be created as with fw_cfg_add_file(), and NULL
is returned to the caller. In any case, the data referenced by the
starting pointer is only linked, NOT copied, into the fw_cfg data
structure.
== fw_cfg_add_callback() ==
Like fw_cfg_add_bytes(), but additionally sets pointers to a callback
function (and opaque argument), which will be executed host-side by
QEMU each time a guest-side write operation to this particular item
completes fully overwriting the item's data.
NOTE: This function is deprecated, and will be completely removed
starting with QEMU v2.4.
== Externally Provided Items ==
= Externally Provided Items =
As of v2.4, "file" fw_cfg items (i.e., items with selector keys above
FW_CFG_FILE_FIRST, and with a corresponding entry in the fw_cfg file