uavcan.protocol.file.* doc fixes

dsdl/uavcan/protocol/file/580.GetInfo.uavcan

@@ -11,7 +11,7 @@ Path path
 
 ---
 
-uint64 crc64     # Ignored/Zero for directories
+uint64 crc64     # Undefined for directories
-uint32 size      # Ignored/Zero for directories
+uint32 size      # Undefined for directories
 Error error
 EntryType entry_type

dsdl/uavcan/protocol/file/583.Read.uavcan

@@ -4,7 +4,7 @@
 # Non-empty data means the end of file is not reached yet, even if the length is less than maximum.
 # Thus, if the client needs to fetch the entire file, it should repeatedly call this service while increasing the
 # offset, until the empty data is returned.
-# If the object pointed by 'path' cannot be read (e.g. is a directory or does not exist), appropriate error code
+# If the object pointed by 'path' cannot be read (e.g. it is a directory or it does not exist), appropriate error code
 # will be returned.
 #
 

dsdl/uavcan/protocol/file/584.Write.uavcan

@@ -4,16 +4,15 @@
 # the field 'offset'.
 #
 # When writing a file, the client should repeatedly call this service with data while advancing offset until the file
-# is written completely. Then the client shall call the service one last time, with the offset equal the size of the
+# is written completely. When write is complete, the client shall call the service one last time, with the offset
-# file and the data field empty, which will signal the server that the write operation is complete.
+# set to the size of the file and with the data field empty, which will signal the server that the write operation is
+# complete.
 #
 # When the write operation is complete, the server shall truncate the resulting file past the specified offset.
 #
 # Server implementation advice:
 # It is recommended to implement proper handling of concurrent writes to the same file from different clients, for
-# example by means of creating a staging area for uncompleted writes (like FTP servers do). Then the write-complete
+# example by means of creating a staging area for uncompleted writes (like FTP servers do).
-# calls (with empty data fields, as described above) will trigger the server to move the file from the staging area
-# to the proper location specified by 'path'.
 #
 
 uint32 offset

dsdl/uavcan/protocol/file/589.BeginFirmwareUpdate.uavcan

@@ -1,26 +1,28 @@
 #
-# This service initiates the firmware update procedure on a remote node.
+# This service initiates a firmware update on a remote node.
-# The node that is being updated will retrieve the firmware image file 'image_file_remote_path' from the node
-# 'source_node_id' using the file read service, update the firmware, and reboot. Alternatively, this service
-# can be used to invoke the default CAN bootloader on a MCU, in which case the field 'image_file_remote_path'
-# must be empty.
 #
-# Nodes are allowed to explicitly reject this request under some circumstances (e.g. BLDC drive should reject if
+# The node that is being updated (slave) will retrieve the firmware image file 'image_file_remote_path' from the node
-# the motor is running).
+# 'source_node_id' using the file read service, then it will update the firmware and reboot. Alternatively, this
+# service can be used to invoke an alternative CAN bootloader (e.g. STM32 system memory bootloader), in which case
+# the field 'image_file_remote_path' must be empty.
 #
-# If the node accepts the request, initiator will get the response immediately, before the update process actually
+# The slave can explicitly reject this request if it is not possible to update the firmware at the moment
-# begins.
+# (e.g. if the node is busy).
+#
+# If the slave node accepts this request, the initiator will get a response immediately, before the update process
+# actually begins.
+#
+# While the firmware is being updated, the slave should set its status code (uavcan.protocol.NodeStatus.status_code)
+# to STATUS_INITIALIZING.
 #
 
 uint8 source_node_id         # If there is an invalid value (e.g. zero), the caller Node ID will be used instead
-Path image_file_remote_path  # Empty to invoke the built-in bootloader
+Path image_file_remote_path  # Empty to invoke an alternative bootloader
 
 ---
 
 uint8 ERROR_OK               = 0
 uint8 ERROR_INVALID_MODE     = 1    # Cannot perform the update right now (e.g. the vehicle is operating)
-uint8 ERROR_INVALID_FIRMWARE = 2    # Wrong firmware image, or this image cannot be loaded via UAVCAN
-uint8 ERROR_FILE_READ_FAILED = 3    # Remote image file could not be read
 uint8 ERROR_UNKNOWN          = 255
 
 uint8 error