From 9c4a5c55f5c6c63c24c29e5a3b57ddbc1e550303 Mon Sep 17 00:00:00 2001 From: "Gabriel L. Somlo" Date: Thu, 5 Nov 2015 09:32:47 -0500 Subject: fw_cfg: move internal function call docs to header file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Cc: Laszlo Ersek Cc: Gerd Hoffmann Cc: Marc Marí Cc: Jordan Justen Cc: Paolo Bonzini Cc: Peter Maydell Signed-off-by: Gabriel Somlo Reviewed-by: Laszlo Ersek Message-id: 1446733972-1602-2-git-send-email-somlo@cmu.edu Signed-off-by: Gerd Hoffmann --- docs/specs/fw_cfg.txt | 85 +-------------------------------------------------- 1 file changed, 1 insertion(+), 84 deletions(-) (limited to 'docs/specs') diff --git a/docs/specs/fw_cfg.txt b/docs/specs/fw_cfg.txt index b8c794f..2099ad9 100644 --- a/docs/specs/fw_cfg.txt +++ b/docs/specs/fw_cfg.txt @@ -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 -- cgit v1.1