Ping...
I'd like to know what's the process of a new virtio device can be merged?
Anybody can tell me? Thanks a lot.
Taking Virtio-gpu as an example, the virtio-gpu had been merged in Linux kernel
And Qemu communities, but the corresponding virtio-gpu spec hadn't been merged
yet. Why was that? Am I missing some rules? Thanks.
Regards,
-Gonglei
> -----Original Message-----
> From: Gonglei (Arei)
> Sent: Sunday, June 26, 2016 5:35 PM
> To: virtio-...@lists.oasis-open.org; qemu-devel@nongnu.org; Gonglei (Arei)
> Cc: Hanweidong (Randy); Stefan Hajnoczi; Cornelia Huck; m...@redhat.com;
> Lingli Deng; Jani Kokkonen; Luonengjun; Huangpeng (Peter); Zhoujian (jay,
> Euler); chenshanxi 00222737; 'Ola liljed...@arm.com'; Varun Sethi
> Subject: [RFC v4] virtio-crypto specification
>
> Hi all,
>
> This is the specification (version 4) about a new virtio crypto device.
>
> Changes from v3:
> - Don't use enum is the spec but macros in specific structures. [Michael &
> Stefan]
> - Add two complete structures for session creation and closing, so that
> the spec is clear on how to lay out the request. [Stefan]
> - Definite the crypto operation request with assigned structure, in this way,
> each data request only occupies *one entry* of the Vring descriptor table,
> which *improves* the *throughput* of data transferring.
>
> Changes from v2:
> - Reserve virtio device ID 20 for crypto device. [Cornelia]
> - Drop all feature bits, those capabilities are offered by the device all
> the time.
> [Stefan & Cornelia]
> - Add a new section 1.4.2 for driver requirements. [Stefan]
> - Use definite type definition instead of enum type in some structure.
> [Stefan]
> - Add virtio_crypto_cipher_alg definition. [Stefan]
> - Add a "Device requirements" section as using MUST. [Stefan]
> - Some grammar nits fixes and typo fixes. [Stefan & Cornelia]
> - Add one VIRTIO_CRYPTO_S_STARTED status for the driver as the flag of
> virtio-crypto device started and can work now.
>
> Great thanks for Stefan and Cornelia!
>
> Changes from v1:
> - Drop the feature bit definition for each algorithm, and using config space
> instead [Cornelia]
> - Add multiqueue support and add corresponding feature bit
> - Update Encryption process and header definition
> - Add session operation process and add corresponding header description
> - Other better description in order to fit for virtio spec [Michael]
> - Some other trivial fixes.
>
> If you have any comments, please let me know, thanks :)
>
>
> Virtio-crypto device Spec
> Signed-off-by: Gonglei
> <arei.gong...@huawei.com>
>
> 1 Crypto Device
> The virtio crypto device is a virtual crypto device (ie. hardware crypto
> accelerator card). The encryption and decryption requests of are placed in the
> data queue, and handled by the real hardware crypto accelerators finally. The
> second queue is the control queue, which is used to create or destroy session
> for symmetric algorithms, and to control some advanced features in the future.
> 1.1 Device ID
> 20
> 1.2 Virtqueues
> 0 dataq
> …
> N-1 dataq
> N controlq
> N is set by max_virtqueues (max_virtqueues >= 1).
> 1.3 Feature bits
> There are no feature bits (yet).
> 1.4 Device configuration layout
> Three driver-read-only configuration fields are currently defined. One
> read-only
> bit (for the device) is currently defined for the status field:
> VIRTIO_CRYPTO_S_HW_READY. One read-only bit (for the driver) is currently
> defined for the status field: VIRTIO_CRYPTO_S_STARTED.
> #define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
> #define VIRTIO_CRYPTO_S_STARTED (1 << 1)
>
> The following driver-read-only field, max_virtqueues specifies the maximum
> number of data virtqueues (dataq1. . .dataqN) .
> struct virtio_crypto_config {
> le16 status;
> le16 max_virtqueues;
> le32 algorithms;
> };
>
> The last driver-read-only field, algorithms specifies the algorithms which the
> device offered. Two read-only bits (for the driver) are currently defined for
> the
> algorithms field: VIRTIO_CRYPTO_ALG_SYM and VIRTIO_CRYPTO_ALG_ASYM.
> #define VIRTIO_CRYPTO_ALG_SYM (1 << 0)
> #define VIRTIO_CRYPTO_ALG_ASYM (1 << 1)
> 1.4.1 Device Requirements: Device configuration layout
> The device MUST set max_virtqueues to between 1 and 65535 inclusive.
>
> The device SHOULD set status according to the status of the hardware-backed
> implementation.
>
> The device MUST set algorithms according to the algorithms which the device
> offered.
> 1.4.2 Driver Requirements: Device configuration layout
> The driver MUST read the ready status from the bottom bit of status to check
> whether the hardware-backed implementation is ready or not.
> The driver MUST read the algorithms to discover the algorithms which the
> device supports.
> 1.5 Device Initialization
> A driver would perform a typical initialization routine like so:
> 1. Identify and initialize data virtqueue, up to max_virtqueues.
> 2. Identify the control virtqueue.
> 3. Identify the ready status of hardware-backend comes from the bottom bit of
> status.
> 4. Read the supported algorithms from bits of algorithms.
> 1.6 Device Operation
> 1.6.1 Session operation
> The symmetric algorithms have the concept of sessions. A session is a handle
> which describes the
> cryptographic parameters to be applied to a number of buffers. The data within
> a session handle includes the following:
> •1. The operation (cipher, hash or both, and if both, the order in which the
> algorithms should be applied).
> •2. The cipher setup data, including the cipher algorithm and mode, the key
> and its length, and the direction (encrypt or decrypt).
> •3. The hash setup data, including the hash algorithm, mode (plain, nested or
> authenticated), and digest result length (to allow for truncation).
> Authenticated mode can refer to HMAC, which requires that the key and
> its length are also specified. It is also used for GCM and CCM authenticated
> encryption, in which case the AAD length is also specified.
> For nested mode, the inner and outer prefix data and length are
> specified, as well as the outer hash algorithm.
>
> The controlq virtqueue is used to control session operations, including
> creation
> or close. The request is preceded by a header:
> struct virtio_crypto_sym_ctlhdr {
> /* control type */
> u8 type;
> };
> Two bits are currently defined for the control header type:
> #define VIRTIO_CRYPTO_CTRL_CREATE_SESSION 1
> #define VIRTIO_CRYPTO_CTRL_CLOSE_SESSION 2
>
> 1.6.1.1 Session creation operation
> A request of creating a session including the following information:
> struct virtio_crypto_sym_session_creation {
> struct virtio_crypto_sym_ctlhdr ctlhdr; /* OUT */
> struct virtio_crypto_sym_session_op session_op; /* OUT */
> struct virtio_crypto_sym_session_op_inhdr inhdr; /* IN */
> };
> The details of specific structure, including struct
> virtio_crypto_sym_session_op
> and struct virtio_crypto_sym_session_op_inhdr are defined by the following
> sections.
> 1.6.1.1.1 Driver Requirements: Session creation operation
> The driver MUST set the control type with
> VIRTIO_CRYPTO_CTRL_CREATE_SESSION before the request is preceded by an
> operation header when executing session creation:
> typedef struct virtio_crypto_sym_session_op {
> /**< No operation */
> #define VIRTIO_CRYPTO_SYM_OP_NONE 0
> /**< Cipher only operation on the data */
> #define VIRTIO_CRYPTO_SYM_OP_CIPHER 1
> /**< Hash only operation on the data */
> #define VIRTIO_CRYPTO_SYM_OP_HASH 2
> /**< Chain any cipher with any hash operation */
> #define VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING 3
> u8 op_type; /* Operation type */
> virtio_crypto_sym_cipher_t cipher_setup_data;
> virtio_crypto_sym_hash_t hash_setup_data;
> /* Perform the hash operation followed by the cipher operation */
> #define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER
> 1
> /* Perform the cipher operation followed by the hash operation */
> #define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH
> 2
> u8 alg_chain_order;
> } virtio_crypto_sym_session_op_t;
> And the structures definition details are:
> typedef struct virtio_crypto_sym_hash_auth_mode {
> /* length of authenticated key */
> le32 auth_key_len;
> /* The length of the additional authenticated data (AAD) in bytes */
> le32 aad_len;
> } virtio_crypto_sym_hash_auth_mode_t;
>
> typedef struct virtio_crypto_sym_cipher {
> /* Option to not do any cryptography */
> #define VIRTIO_CRYPTO_NO_CIPHER 0
> #define VIRTIO_CRYPTO_CIPHER_DES 1
> #define VIRTIO_CRYPTO_CIPHER_DES_CBC 2
> #define VIRTIO_CRYPTO_CIPHER_DES3 3
> #define VIRTIO_CRYPTO_CIPHER_DES3_CBC 4
> #define VIRTIO_CRYPTO_CIPHER_AES 5
> #define VIRTIO_CRYPTO_CIPHER_AES_CBC 6
> #define VIRTIO_CRYPTO_CIPHER_KASUMI_F8 7
> le32 alg; /* cipher algorithm type (ie. aes-cbc ) */
> /* length of key */
> le32 keylen;
> #define VIRTIO_CRYPTO_DECRYPT 0
> #define VIRTIO_CRYPTO_ENCRYPT 1
> u8 op; /* encrypt or decrypt */
> } virtio_crypto_sym_cipher_t;
>
> typedef struct virtio_crypto_sym_hash {
> /* Option to not do any hash */
> #define VIRTIO_CRYPTO_NO_HASH 0
> #define VIRTIO_CRYPTO_HASH_MD5 1
> #define VIRTIO_CRYPTO_HASH_SHA1 2
> #define VIRTIO_CRYPTO_HASH_SHA1_96 3
> #define VIRTIO_CRYPTO_HASH_SHA224 4
> #define VIRTIO_CRYPTO_HASH_SHA256 5
> #define VIRTIO_CRYPTO_HASH_SHA384 6
> #define VIRTIO_CRYPTO_HASH_SHA512 7
> #define VIRTIO_CRYPTO_HASH_AES_XCBC 8
> #define VIRTIO_CRYPTO_HASH_AES_XCBC_96 9
> #define VIRTIO_CRYPTO_HASH_KASUMI_F9 10
> le32 hash_alg; /* hash algorithm type */
> #define VIRTIO_CRYPTO_SYM_HASH_MODE_PLAIN 1
> #define VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH 2
> #define VIRTIO_CRYPTO_SYM_HASH_MODE_NESTED 3
> u8 hash_mode; /* mode of hash operation, including
> authenticated/plain/nested hash */
> /* hash result length */
> le32 hash_result_len;
> virtio_crypto_sym_hash_auth_mode_t auth_mode_setup_data;
> } virtio_crypto_sym_hash_t;
> The driver MUST set the control type with
> VIRTIO_CRYPTO_CTRL_CLOSE_SESSION and pass the session_id to the device
> when executing session close.
> 1.6.1.1.2 Device Requirements: Session creation operation
> The device MUST return a session identifier to the driver when the device
> finishes the processing of session close. The session creation request MUST
> end by a tailer:
> typedef struct virtio_crypto_sym_session_op_inhdr {
> u8 status;
> le64 session_id;
> } virtio_crypto_sym_session_op_inhdr_t;
> Both status and session_id are written by the device: either
> VIRTIO_CRYPTO_CTRL_OK for success, VIRTIO_CRYPTO_CTRL_ERR for
> creation failed or device error.
> #define VIRTIO_CRYPTO_CTRL_OK 0
> #define VIRTIO_CRYPTO_CTRL_ERR 1
> 1.6.1.2 Session closing operation
> A request of closing a session including the following information:
> struct virtio_crypto_sym_session_creation {
> struct virtio_crypto_sym_ctlhdr ctlhdr; /* OUT */
> le64 session_id; /* OUT */
> u8 status; /* IN */
> };
> 1.6.1.2.1 Driver Requirements: Session closing operation
> The driver MUST set the control type with
> VIRTIO_CRYPTO_CTRL_CLOSE_SESSION, and the session_id MUST be a valid
> value which assigned by the device when a session was created.
> 1.6.1.2.2 Device Requirements: Session closing operation
> Status is written by the device: either VIRTIO_CRYPTO_CTRL_OK for success,
> VIRTIO_CRYPTO_CTRL_ERR for creation failed or device error.
> #define VIRTIO_CRYPTO_CTRL_OK 0
> #define VIRTIO_CRYPTO_CTRL_ERR 1
> 1.6.2 Encryption operation
> 1.6.2.1 Driver Requirements: Encryption operation
> The encryption and decryption requests and the corresponding results are
> transmitted by placing them in dataq. The symmetric algorithms requests are
> preceded by a header:
> struct virtio_crypto_sym_op_hdr {
> /* the backend returned session identifier */
> le64 session_id;
> /* length of initial vector */
> le32 iv_len;
> /* iv offset in the whole crypto data memory */
> le32 iv_offset;
> /* length of additional auth data */
> le32 auth_len;
> /* additional auth data offset in the whole crypto data memory */
> le32 additional_auth_offset;
> /* cipher start source offest */
> le32 cipher_start_src_offset;
> le32 len_to_cipher;
> /* hash start source offest */
> le32 hash_start_src_offset;
> le32 len_to_hash;
> /* length of source data */
> le32 source_len;
> } ;
> The encryption request MUST end by a tailer:
> typedef struct virtio_crypto_sym_op_inhdr {
> u8 status;
> } virtio_crypto_sym _op_inhdr_t;
> The specific content of symmetric algorithms requests SHOULD be same as
> below:
> struct virtio_crypto_sym_op_data {
> struct virtio_crypto_sym_op_hdr hdr_info;
> le64 iv_addr; /* iv guest address */
> le64 auth_data_addr; /* associated data guest address */
> le64 src_data_addr; /* source data guest address */
> le64 dst_data_addr; /* destination data guest address */
> le64 digest_result_addr; /* digest result guest address */
> le64 inhdr_addr; /* in-header guest address */
> };
> In this way, each data request only occupies one entry of the Vring descriptor
> table, which improves the throughput of data transferring.
> 1.6.2.2 Device Requirements: Encryption operation
> The struct virtio_crypto_sym_op_inhdr’s status byte is written by the device:
> either VIRTIO_CRYPTO_S_OK for success, VIRTIO_CRYPTO_S_ERR for device or
> driver error, VIRTIO_CRYPTO_S_BADMSG for verification failed when decrypt
> AEAD algorithms:
> #define VIRTIO_CRYPTO_S_OK 0
> #define VIRTIO_CRYPTO_S_ERR 1
> #define VIRTIO_CRYPTO_S_BADMSG 2
>
> 1.6.2.3 Steps of encryption Operation
> Step1: Create a session:
> 1. The driver fills out the context message, including algorithm name, key,
> keylen etc;
> 2. The driver sends a context message to the backend device by controlq;
> 3. The device creates a session using the message transmitted by controlq;
> 4. Return the session id to the driver.
> Step 2: Execute the detail encryption operation:
> 1. The driver fills out the encrypt requests;
> 2. Put the requests into dataq and kick the virtqueue;
> 3. The device executes the encryption operation according the requests'
> arguments;
> 4. The device returns the encryption result to the driver by dataq;
> 5. The driver callback handle the result and over.
>
> Note: the driver MAY support both synchronous and asynchronous encryption.
> Then the performance is poor in synchronous operation because frequent
> context switching and virtualization overhead. The driver SHOULD by
> preference use asynchronous encryption.
> 1.6.3 Decryption Operation
> The decryption process is the same with encryption.
> 1.6.3.1 Device Requirements: Decryption operation
> The device MUST verify and return the verify result to the driver. If the
> verify
> result is not correct, VIRTIO_CRYPTO_S_BADMSG (bad message) MUST be
> returned the driver.
>
> Regards,
> -Gonglei
>
>
>
