RE: [PATCH] Documentation: misc-devices: mei: Convert mei txt files to reST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




> -----Original Message-----
> From: Shreeya Patel [mailto:shreeya.patel23498@xxxxxxxxx]
> Sent: Sunday, June 30, 2019 00:32
> To: skhan@xxxxxxxxxxxxxxxxxxx; corbet@xxxxxxx; Winkler, Tomas
> <tomas.winkler@xxxxxxxxx>; linux-doc@xxxxxxxxxxxxxxx; linux-
> kernel@xxxxxxxxxxxxxxx; linux-kernel-mentees@xxxxxxxxxxxxxxxxxxxxxxxxx
> Subject: [PATCH] Documentation: misc-devices: mei: Convert mei txt files to
> reST
> 
> Convert the MEI misc device's documentation files from .txt to
> reStructuredText format. Make a minor change of correcting the wrong macro
> name MEI_CONNECT_CLIENT_IOCTL to IOCTL_MEI_CONNECT_CLIENT.
> Add an index file in mei as there are two sections for it in the documentation.
> 
> Signed-off-by: Shreeya Patel <shreeya.patel23498@xxxxxxxxx>
> ---
Sorry you are late, we've already done that, it should be merged via Greg's char-misc tree.
Thanks
Tomas



> I am not sure if I have placed the Documentation in the right place so I would
> like to get some suggestions from the MAINTAINERS on this part.
> 
>  Documentation/misc-devices/index.rst          |   1 +
>  Documentation/misc-devices/mei/index.rst      |  15 +
>  .../misc-devices/mei/mei-client-bus.rst       | 151 +++++++++
>  .../misc-devices/mei/mei-client-bus.txt       | 141 ---------
>  Documentation/misc-devices/mei/mei.rst        | 289 ++++++++++++++++++
>  Documentation/misc-devices/mei/mei.txt        | 266 ----------------
>  6 files changed, 456 insertions(+), 407 deletions(-)  create mode 100644
> Documentation/misc-devices/mei/index.rst
>  create mode 100644 Documentation/misc-devices/mei/mei-client-bus.rst
>  delete mode 100644 Documentation/misc-devices/mei/mei-client-bus.txt
>  create mode 100644 Documentation/misc-devices/mei/mei.rst
>  delete mode 100644 Documentation/misc-devices/mei/mei.txt
> 
> diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-
> devices/index.rst
> index dfd1f45a3127..e788a12b2b19 100644
> --- a/Documentation/misc-devices/index.rst
> +++ b/Documentation/misc-devices/index.rst
> @@ -15,3 +15,4 @@ fit into other categories.
>     :maxdepth: 2
> 
>     ibmvmc
> +   mei/index
> diff --git a/Documentation/misc-devices/mei/index.rst b/Documentation/misc-
> devices/mei/index.rst
> new file mode 100644
> index 000000000000..3018098ad075
> --- /dev/null
> +++ b/Documentation/misc-devices/mei/index.rst
> @@ -0,0 +1,15 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================================================
> ==
> +Intel(R) Management Engine Interface Kernel Driver (Intel(R) MEI)
> +===============================================================
> ==
> +
> +.. class:: toc-title
> +
> +           Table of contents
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   mei
> +   mei-client-bus
> diff --git a/Documentation/misc-devices/mei/mei-client-bus.rst
> b/Documentation/misc-devices/mei/mei-client-bus.rst
> new file mode 100644
> index 000000000000..82d455afae78
> --- /dev/null
> +++ b/Documentation/misc-devices/mei/mei-client-bus.rst
> @@ -0,0 +1,151 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============================================
> +Intel(R) Management Engine (ME) Client bus API
> +==============================================
> +
> +
> +Rationale
> +=========
> +
> +MEI misc character device is useful for dedicated applications to send
> +and receive data to the many FW appliance found in Intel's ME from the user
> space.
> +However for some of the ME functionalities it make sense to leverage
> +existing software stack and expose them through existing kernel subsystems.
> +
> +In order to plug seamlessly into the kernel device driver model we add
> +kernel virtual bus abstraction on top of the MEI driver. This allows
> +implementing linux kernel drivers for the various MEI features as a stand
> alone entities found in their respective subsystem.
> +Existing device drivers can even potentially be re-used by adding an
> +MEI CL bus layer to the existing code.
> +
> +
> +MEI CL bus API
> +==============
> +
> +A driver implementation for an MEI Client is very similar to existing
> +bus based device drivers. The driver registers itself as an MEI CL bus
> +driver through the :c:type:`mei_cl_driver` structure:
> +
> +::
> +
> +        struct mei_cl_driver {
> +	        struct device_driver driver;
> +	        const char *name;
> +
> +	        const struct mei_cl_device_id *id_table;
> +
> +	        int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id
> *id);
> +	        int (*remove)(struct mei_cl_device *dev);
> +        };
> +
> +        struct mei_cl_id {
> +	        char name[MEI_NAME_SIZE];
> +	        kernel_ulong_t driver_info;
> +        };
> +
> +
> +The :c:type:`mei_cl_id` structure allows the driver to bind itself against a
> device name.
> +
> +To actually register a driver on the ME Client bus one must call the
> +:c:func:`mei_cl_add_driver()` API. This is typically called at module init time.
> +
> +Once registered on the ME Client bus, a driver will typically try to do
> +some I/O on this bus and this should be done through the
> +:c:func:`mei_cl_send()` and :c:func:`mei_cl_recv()` routines. The latter is
> synchronous (blocks and sleeps until data shows up).
> +In order for drivers to be notified of pending events waiting for them (e.g.
> +an Rx event) they can register an event handler through the
> +:c:func:`mei_cl_register_event_cb()` routine. Currently only the
> +:c:macro:`MEI_EVENT_RX` event will trigger an event handler call and
> +the driver implementation is supposed to call :c:func:`mei_recv()` from
> +the event handler in order to fetch the pending received buffers.
> +
> +
> +Example
> +=======
> +
> +As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
> +The driver init and exit routines for this device would look like:
> +
> +::
> +
> +        #define CONTACT_DRIVER_NAME "contact"
> +
> +        static struct mei_cl_device_id contact_mei_cl_tbl[] = {
> +	        { CONTACT_DRIVER_NAME, },
> +	        /* required last entry */
> +	        { }
> +        };
> +        MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
> +
> +        static struct mei_cl_driver contact_driver = {
> +	        .id_table = contact_mei_tbl,
> +	        .name = CONTACT_DRIVER_NAME,
> +	        .probe = contact_probe,
> +	        .remove = contact_remove,
> +        };
> +
> +        static int contact_init(void)
> +        {
> +	        int r;
> +
> +	        r = mei_cl_driver_register(&contact_driver);
> +	        if (r) {
> +		        pr_err(CONTACT_DRIVER_NAME ": driver registration
> failed\n");
> +		        return r;
> +	        }
> +
> +	        return 0;
> +        }
> +
> +        static void __exit contact_exit(void)
> +        {
> +	        mei_cl_driver_unregister(&contact_driver);
> +        }
> +
> +        module_init(contact_init);
> +        module_exit(contact_exit);
> +
> +And the driver's simplified probe routine would look like that:
> +
> +::
> +
> +        int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id
> *id)
> +        {
> +	        struct contact_driver *contact;
> +
> +	        [...]
> +	        mei_cl_enable_device(dev);
> +
> +	        mei_cl_register_event_cb(dev, contact_event_cb, contact);
> +
> +	        return 0;
> +        }
> +
> +In the probe routine the driver first enable the MEI device and then
> +registers an ME bus event handler which is as close as it can get to
> +registering a threaded IRQ handler.
> +The handler implementation will typically call some I/O routine
> +depending on the pending events:
> +
> +::
> +
> +        #define MAX_NFC_PAYLOAD 128
> +
> +        static void contact_event_cb(struct mei_cl_device *dev, u32 events,
> +                                     void *context)
> +        {
> +	        struct contact_driver *contact = context;
> +
> +	        if (events & BIT(MEI_EVENT_RX)) {
> +		        u8 payload[MAX_NFC_PAYLOAD];
> +		        int payload_size;
> +
> +		        payload_size = mei_recv(dev, payload,
> MAX_NFC_PAYLOAD);
> +		        if (payload_size <= 0)
> +			        return;
> +
> +		        /* Hook to the NFC subsystem */
> +		        nfc_hci_recv_frame(contact->hdev, payload,
> payload_size);
> +	        }
> +        }
> diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt
> b/Documentation/misc-devices/mei/mei-client-bus.txt
> deleted file mode 100644
> index 743be4ec8989..000000000000
> --- a/Documentation/misc-devices/mei/mei-client-bus.txt
> +++ /dev/null
> @@ -1,141 +0,0 @@
> -Intel(R) Management Engine (ME) Client bus API -
> ==============================================
> -
> -
> -Rationale
> -=========
> -
> -MEI misc character device is useful for dedicated applications to send and
> receive -data to the many FW appliance found in Intel's ME from the user
> space.
> -However for some of the ME functionalities it make sense to leverage existing
> software -stack and expose them through existing kernel subsystems.
> -
> -In order to plug seamlessly into the kernel device driver model we add kernel
> virtual -bus abstraction on top of the MEI driver. This allows implementing linux
> kernel drivers -for the various MEI features as a stand alone entities found in
> their respective subsystem.
> -Existing device drivers can even potentially be re-used by adding an MEI CL
> bus layer to -the existing code.
> -
> -
> -MEI CL bus API
> -==============
> -
> -A driver implementation for an MEI Client is very similar to existing bus -based
> device drivers. The driver registers itself as an MEI CL bus driver through -the
> mei_cl_driver structure:
> -
> -struct mei_cl_driver {
> -	struct device_driver driver;
> -	const char *name;
> -
> -	const struct mei_cl_device_id *id_table;
> -
> -	int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
> -	int (*remove)(struct mei_cl_device *dev);
> -};
> -
> -struct mei_cl_id {
> -	char name[MEI_NAME_SIZE];
> -	kernel_ulong_t driver_info;
> -};
> -
> -The mei_cl_id structure allows the driver to bind itself against a device name.
> -
> -To actually register a driver on the ME Client bus one must call the
> mei_cl_add_driver() -API. This is typically called at module init time.
> -
> -Once registered on the ME Client bus, a driver will typically try to do some I/O
> on -this bus and this should be done through the mei_cl_send() and
> mei_cl_recv() -routines. The latter is synchronous (blocks and sleeps until data
> shows up).
> -In order for drivers to be notified of pending events waiting for them (e.g.
> -an Rx event) they can register an event handler through the
> -mei_cl_register_event_cb() routine. Currently only the MEI_EVENT_RX event -
> will trigger an event handler call and the driver implementation is supposed -to
> call mei_recv() from the event handler in order to fetch the pending -received
> buffers.
> -
> -
> -Example
> -=======
> -
> -As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
> -The driver init and exit routines for this device would look like:
> -
> -#define CONTACT_DRIVER_NAME "contact"
> -
> -static struct mei_cl_device_id contact_mei_cl_tbl[] = {
> -	{ CONTACT_DRIVER_NAME, },
> -
> -	/* required last entry */
> -	{ }
> -};
> -MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
> -
> -static struct mei_cl_driver contact_driver = {
> -	.id_table = contact_mei_tbl,
> -	.name = CONTACT_DRIVER_NAME,
> -
> -	.probe = contact_probe,
> -	.remove = contact_remove,
> -};
> -
> -static int contact_init(void)
> -{
> -	int r;
> -
> -	r = mei_cl_driver_register(&contact_driver);
> -	if (r) {
> -		pr_err(CONTACT_DRIVER_NAME ": driver registration
> failed\n");
> -		return r;
> -	}
> -
> -	return 0;
> -}
> -
> -static void __exit contact_exit(void)
> -{
> -	mei_cl_driver_unregister(&contact_driver);
> -}
> -
> -module_init(contact_init);
> -module_exit(contact_exit);
> -
> -And the driver's simplified probe routine would look like that:
> -
> -int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id) -{
> -	struct contact_driver *contact;
> -
> -	[...]
> -	mei_cl_enable_device(dev);
> -
> -	mei_cl_register_event_cb(dev, contact_event_cb, contact);
> -
> -	return 0;
> -}
> -
> -In the probe routine the driver first enable the MEI device and then registers -
> an ME bus event handler which is as close as it can get to registering a -
> threaded IRQ handler.
> -The handler implementation will typically call some I/O routine depending on -
> the pending events:
> -
> -#define MAX_NFC_PAYLOAD 128
> -
> -static void contact_event_cb(struct mei_cl_device *dev, u32 events,
> -			     void *context)
> -{
> -	struct contact_driver *contact = context;
> -
> -	if (events & BIT(MEI_EVENT_RX)) {
> -		u8 payload[MAX_NFC_PAYLOAD];
> -		int payload_size;
> -
> -		payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
> -		if (payload_size <= 0)
> -			return;
> -
> -		/* Hook to the NFC subsystem */
> -		nfc_hci_recv_frame(contact->hdev, payload, payload_size);
> -	}
> -}
> diff --git a/Documentation/misc-devices/mei/mei.rst b/Documentation/misc-
> devices/mei/mei.rst
> new file mode 100644
> index 000000000000..e91ac2570b4d
> --- /dev/null
> +++ b/Documentation/misc-devices/mei/mei.rst
> @@ -0,0 +1,289 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +====================================
> +Intel(R) Management Engine Interface
> +====================================
> +
> +Introduction
> +============
> +
> +The Intel Management Engine (Intel ME) is an isolated and protected
> +computing resource (Co-processor) residing inside certain Intel
> +chipsets. The Intel ME provides support for computer/IT management
> +features. The feature set depends on the Intel chipset SKU.
> +
> +The Intel Management Engine Interface (Intel MEI, previously known as
> +HECI) is the interface between the Host and Intel ME. This interface is
> +exposed to the host as a PCI device. The Intel MEI Driver is in charge
> +of the communication channel between a host application and the Intel ME
> feature.
> +
> +Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and
> +each client has its own protocol. The protocol is message-based with a
> +header and payload up to 512 bytes.
> +
> +Prominent usage of the Intel ME Interface is to communicate with
> +Intel(R) Active Management Technology (Intel AMT) implemented in
> +firmware running on the Intel ME.
> +
> +Intel AMT provides the ability to manage a host remotely out-of-band
> +(OOB) even when the operating system running on the host processor has
> +crashed or is in a sleep state.
> +
> +Some examples of Intel AMT usage are:
> +        * Monitoring hardware state and platform components
> +        * Remote power off/on (useful for green computing or overnight IT
> +          maintenance)
> +        * OS updates
> +        * Storage of useful platform information such as software assets
> +        * Built-in hardware KVM
> +        * Selective network isolation of Ethernet and IP protocol flows based
> +          on policies set by a remote management console
> +        * IDE device redirection from remote management console
> +
> +Intel AMT (OOB) communication is based on SOAP (deprecated starting
> +with Release 6.0) over HTTP/S or WS-Management protocol over HTTP/S
> +that are received from a remote management console application.
> +
> +For more information about Intel AMT:
> +`<http://software.intel.com/sites/manageability/AMT_Implementation_and_
> +Reference_Guide>`_
> +
> +
> +Intel MEI Driver
> +================
> +
> +The driver exposes a misc device called :file:`/dev/mei`.
> +
> +An application maintains communication with an Intel ME feature while
> +:file:`/dev/mei` is open. The binding to a specific feature is
> +performed by calling :c:macro:`IOCTL_MEI_CONNECT_CLIENT`, which passes
> the desired UUID.
> +The number of instances of an Intel ME feature that can be opened at
> +the same time depends on the Intel ME feature, but most of the features
> +allow only a single instance.
> +
> +The Intel AMT Host Interface (Intel AMTHI) feature supports multiple
> +simultaneous user connected applications. The Intel MEI driver handles
> +this internally by maintaining request queues for the applications.
> +
> +The driver is transparent to data that are passed between firmware
> +feature and host application.
> +
> +Because some of the Intel ME features can change the system
> +configuration, the driver by default allows only a privileged user to
> +access it.
> +
> +A code snippet for an application communicating with Intel AMTHI client:
> +
> +::
> +
> +        struct mei_connect_client_data data;
> +        fd = open(MEI_DEVICE);
> +
> +        data.d.in_client_uuid = AMTHI_UUID;
> +
> +        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
> +
> +        printf("Ver=%d, MaxLen=%ld\n",
> +               data.d.in_client_uuid.protocol_version,
> +               data.d.in_client_uuid.max_msg_length);
> +
> +        [...]
> +
> +        write(fd, amthi_req_data, amthi_req_data_len);
> +
> +        [...]
> +
> +        read(fd, &amthi_res_data, amthi_res_data_len);
> +
> +        [...]
> +
> +        close(fd);
> +
> +
> +IOCTL
> +=====
> +
> +The Intel MEI Driver supports the following IOCTL commands:
> +
> +
> +:c:macro:`IOCTL_MEI_CONNECT_CLIENT`
> +-------------------------------------
> +Connect to firmware Feature (client)
> +
> +**Usage:**
> +
> +::
> +
> +        struct mei_connect_client_data clientData;
> +        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
> +
> +**Inputs:**
> +        :c:type:`mei_connect_client_data` - structure contain the following
> +        input field.
> +
> +        :c:data:`in_client_uuid` - UUID of the FW Feature that needs to connect
> to.
> +
> +**Outputs:**
> +        :c:data:`out_client_properties` - Client Properties: MTU and Protocol
> Version.
> +
> +**Error returns:**
> +        | :c:macro:`EINVAL` -  Wrong IOCTL Number.
> +        | :c:macro:`ENODEV` -  Device or Connection is not initialized or ready.
> (e.g. Wrong UUID).
> +        | :c:macro:`ENOMEM` - Unable to allocate memory to client internal
> data.
> +        | :c:macro:`EFAULT` -  Fatal Error (e.g. Unable to access user input data).
> +        | :c:macro:`EBUSY` -  Connection Already Open.
> +
> +**Notes:**
> +        :c:data:`max_msg_length` (MTU) in client properties describes the
> maximum
> +        data that can be sent or received. (e.g. if MTU=2K, can send
> +        requests up to bytes 2k and received responses up to 2k bytes).
> +
> +
> +:c:macro:`IOCTL_MEI_NOTIFY_SET`
> +-------------------------------
> +Enable or disable event notifications
> +
> +**Usage:**
> +
> +::
> +
> +        uint32_t enable;
> +        ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
> +
> +**Inputs:**
> +        | :c:data:`uint32_t enable = 1;`
> +        | or
> +        | :c:data:`uint32_t enable[disable] = 0;`
> +
> +**Error returns:**
> +        | :c:macro:`EINVAL` - Wrong IOCTL Number.
> +        | :c:macro:`ENODEV` - Device  is not initialized or the client not
> connected.
> +        | :c:macro:`ENOMEM` - Unable to allocate memory to client internal
> data.
> +        | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
> +        | :c:macro:`EOPNOTSUPP` - if the device doesn't support the feature.
> +
> +**Notes:**
> +        The client must be connected in order to enable notification events.
> +
> +
> +:c:macro:`IOCTL_MEI_NOTIFY_GET`
> +-------------------------------
> +Retrieve event
> +
> +**Usage:**
> +
> +::
> +
> +        uint32_t event;
> +        ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
> +
> +**Outputs:**
> +        | 1 - if an event is pending.
> +        | 0 - if there is no even pending.
> +
> +**Error returns:**
> +        | :c:macro:`EINVAL` - Wrong IOCTL Number.
> +        | :c:macro:`ENODEV` - Device is not initialized or the client not
> connected.
> +        | :c:macro:`ENOMEM` - Unable to allocate memory to client internal
> data.
> +        | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
> +        | :c:macro:`EOPNOTSUPP` - if the device doesn't support the feature.
> +
> +**Notes:**
> +        The client must be connected and event notification has to be enabled
> +        in order to receive an event.
> +
> +
> +Intel ME Applications
> +=====================
> +
> +1) Intel Local Management Service (Intel LMS)
> +
> +        Applications running locally on the platform communicate with Intel AMT
> Release
> +        2.0 and later releases in the same way that network applications do via
> SOAP
> +        over HTTP (deprecated starting with Release 6.0) or with WS-
> Management over
> +        SOAP over HTTP. This means that some Intel AMT features can be
> accessed from a
> +        local application using the same network interface as a remote
> application
> +        communicating with Intel AMT over the network.
> +
> +        When a local application sends a message addressed to the local Intel
> AMT host
> +        name, the Intel LMS, which listens for traffic directed to the host name,
> +        intercepts the message and routes it to the Intel MEI.
> +        For more information:
> +
> `<http://software.intel.com/sites/manageability/AMT_Implementation_and_Re
> ference_Guide>`_
> +        Under "About Intel AMT" => "Local Access"
> +
> +        For downloading Intel LMS:
> +
> + `<http://software.intel.com/en-us/articles/download-the-latest-intel-a
> + mt-open-source-drivers/>`_
> +
> +        The Intel LMS opens a connection using the Intel MEI driver to the Intel
> LMS
> +        firmware feature using a defined UUID and then communicates with the
> feature
> +        using a protocol called Intel AMT Port Forwarding Protocol (Intel APF
> protocol).
> +        The protocol is used to maintain multiple sessions with Intel AMT from a
> +        single application.
> +
> +        See the protocol specification in the `Intel AMT Software Development
> Kit (SDK)
> +
> <http://software.intel.com/sites/manageability/AMT_Implementation_and_Ref
> erence_Guide>`_
> +        Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
> +        => "Information for Intel(R) vPro(TM) Gateway Developers"
> +        => "Description of the Intel AMT Port Forwarding (APF) Protocol"
> +
> +2) Intel AMT Remote configuration using a Local Agent
> +
> +        A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
> +        without requiring installing additional data to enable setup. The remote
> +        configuration process may involve an ISV-developed remote
> configuration
> +        agent that runs on the host.
> +        For more information:
> +
> `<http://software.intel.com/sites/manageability/AMT_Implementation_and_Re
> ference_Guide>`_
> +        Under "Setup and Configuration of Intel AMT" =>
> +        "SDK Tools Supporting Setup and Configuration" =>
> +        "Using the Local Agent Sample"
> +
> +        An open source Intel AMT configuration utility,	implementing a local
> agent
> +        that accesses the Intel MEI driver, can be found here:
> +
> + `<http://software.intel.com/en-us/articles/download-the-latest-intel-a
> + mt-open-source-drivers/>`
> +
> +
> +Intel AMT OS Health Watchdog
> +============================
> +
> +The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
> +Whenever the OS hangs or crashes, Intel AMT will send an event to any
> +subscriber to this event. This mechanism means that IT knows when a
> +platform crashes even when there is a hard failure on the host.
> +
> +The Intel AMT Watchdog is composed of two parts:
> +        1) Firmware feature - receives the heartbeats
> +           and sends an event when the heartbeats stop.
> +        2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
> +           configures the watchdog and sends the heartbeats.
> +
> +The Intel iAMT watchdog MEI driver uses the kernel watchdog API to
> +configure the Intel AMT Watchdog and to send heartbeats to it. The
> +default timeout of the watchdog is 120 seconds.
> +
> +If the Intel AMT is not enabled in the firmware then the watchdog
> +client won't enumerate on the me client bus and watchdog devices won't be
> exposed.
> +
> +
> +Supported Chipsets
> +==================
> +
> +| 7 Series Chipset Family
> +| 6 Series Chipset Family
> +| 5 Series Chipset Family
> +| 4 Series Chipset Family
> +| Mobile 4 Series Chipset Family
> +| ICH9
> +| 82946GZ/GL
> +| 82G35 Express
> +| 82Q963/Q965
> +| 82P965/G965
> +| Mobile PM965/GM965
> +| Mobile GME965/GLE960
> +| 82Q35 Express
> +| 82G33/G31/P35/P31 Express
> +| 82Q33 Express
> +| 82X38/X48 Express
> +
> +---
> +linux-mei@xxxxxxxxxxxxxxx
> diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-
> devices/mei/mei.txt
> deleted file mode 100644
> index 2b80a0cd621f..000000000000
> --- a/Documentation/misc-devices/mei/mei.txt
> +++ /dev/null
> @@ -1,266 +0,0 @@
> -Intel(R) Management Engine Interface (Intel(R) MEI) -
> ===================================================
> -
> -Introduction
> -============
> -
> -The Intel Management Engine (Intel ME) is an isolated and protected
> computing -resource (Co-processor) residing inside certain Intel chipsets. The
> Intel ME -provides support for computer/IT management features. The feature
> set -depends on the Intel chipset SKU.
> -
> -The Intel Management Engine Interface (Intel MEI, previously known as HECI)
> -is the interface between the Host and Intel ME. This interface is exposed -to
> the host as a PCI device. The Intel MEI Driver is in charge of the -
> communication channel between a host application and the Intel ME feature.
> -
> -Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and -each
> client has its own protocol. The protocol is message-based with a -header and
> payload up to 512 bytes.
> -
> -Prominent usage of the Intel ME Interface is to communicate with Intel(R) -
> Active Management Technology (Intel AMT) implemented in firmware running
> on -the Intel ME.
> -
> -Intel AMT provides the ability to manage a host remotely out-of-band (OOB) -
> even when the operating system running on the host processor has crashed or -
> is in a sleep state.
> -
> -Some examples of Intel AMT usage are:
> -   - Monitoring hardware state and platform components
> -   - Remote power off/on (useful for green computing or overnight IT
> -     maintenance)
> -   - OS updates
> -   - Storage of useful platform information such as software assets
> -   - Built-in hardware KVM
> -   - Selective network isolation of Ethernet and IP protocol flows based
> -     on policies set by a remote management console
> -   - IDE device redirection from remote management console
> -
> -Intel AMT (OOB) communication is based on SOAP (deprecated -starting with
> Release 6.0) over HTTP/S or WS-Management protocol over -HTTP/S that are
> received from a remote management console application.
> -
> -For more information about Intel AMT:
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> -
> -
> -Intel MEI Driver
> -================
> -
> -The driver exposes a misc device called /dev/mei.
> -
> -An application maintains communication with an Intel ME feature while -
> /dev/mei is open. The binding to a specific feature is performed by calling -
> MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID.
> -The number of instances of an Intel ME feature that can be opened -at the
> same time depends on the Intel ME feature, but most of the -features allow
> only a single instance.
> -
> -The Intel AMT Host Interface (Intel AMTHI) feature supports multiple -
> simultaneous user connected applications. The Intel MEI driver -handles this
> internally by maintaining request queues for the applications.
> -
> -The driver is transparent to data that are passed between firmware feature -
> and host application.
> -
> -Because some of the Intel ME features can change the system -configuration,
> the driver by default allows only a privileged -user to access it.
> -
> -A code snippet for an application communicating with Intel AMTHI client:
> -
> -	struct mei_connect_client_data data;
> -	fd = open(MEI_DEVICE);
> -
> -	data.d.in_client_uuid = AMTHI_UUID;
> -
> -	ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
> -
> -	printf("Ver=%d, MaxLen=%ld\n",
> -			data.d.in_client_uuid.protocol_version,
> -			data.d.in_client_uuid.max_msg_length);
> -
> -	[...]
> -
> -	write(fd, amthi_req_data, amthi_req_data_len);
> -
> -	[...]
> -
> -	read(fd, &amthi_res_data, amthi_res_data_len);
> -
> -	[...]
> -	close(fd);
> -
> -
> -IOCTL
> -=====
> -
> -The Intel MEI Driver supports the following IOCTL commands:
> -	IOCTL_MEI_CONNECT_CLIENT	Connect to firmware Feature (client).
> -
> -	usage:
> -		struct mei_connect_client_data clientData;
> -		ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
> -
> -	inputs:
> -		mei_connect_client_data struct contain the following
> -		input field:
> -
> -		in_client_uuid -	UUID of the FW Feature that needs
> -					to connect to.
> -	outputs:
> -		out_client_properties - Client Properties: MTU and Protocol
> Version.
> -
> -	error returns:
> -		EINVAL	Wrong IOCTL Number
> -		ENODEV	Device or Connection is not initialized or
> ready.
> -			(e.g. Wrong UUID)
> -		ENOMEM	Unable to allocate memory to client internal
> data.
> -		EFAULT	Fatal Error (e.g. Unable to access user input data)
> -		EBUSY	Connection Already Open
> -
> -	Notes:
> -        max_msg_length (MTU) in client properties describes the maximum
> -        data that can be sent or received. (e.g. if MTU=2K, can send
> -        requests up to bytes 2k and received responses up to 2k bytes).
> -
> -	IOCTL_MEI_NOTIFY_SET: enable or disable event notifications
> -
> -	Usage:
> -		uint32_t enable;
> -		ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
> -
> -	Inputs:
> -		uint32_t enable = 1;
> -		or
> -		uint32_t enable[disable] = 0;
> -
> -	Error returns:
> -		EINVAL	Wrong IOCTL Number
> -		ENODEV	Device  is not initialized or the client not
> connected
> -		ENOMEM	Unable to allocate memory to client internal
> data.
> -		EFAULT	Fatal Error (e.g. Unable to access user input data)
> -		EOPNOTSUPP if the device doesn't support the feature
> -
> -	Notes:
> -	The client must be connected in order to enable notification events
> -
> -
> -	IOCTL_MEI_NOTIFY_GET : retrieve event
> -
> -	Usage:
> -		uint32_t event;
> -		ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
> -
> -	Outputs:
> -		1 - if an event is pending
> -		0 - if there is no even pending
> -
> -	Error returns:
> -		EINVAL	Wrong IOCTL Number
> -		ENODEV	Device is not initialized or the client not
> connected
> -		ENOMEM	Unable to allocate memory to client internal
> data.
> -		EFAULT	Fatal Error (e.g. Unable to access user input data)
> -		EOPNOTSUPP if the device doesn't support the feature
> -
> -	Notes:
> -	The client must be connected and event notification has to be enabled
> -	in order to receive an event
> -
> -
> -Intel ME Applications
> -=====================
> -
> -	1) Intel Local Management Service (Intel LMS)
> -
> -	   Applications running locally on the platform communicate with Intel
> AMT Release
> -	   2.0 and later releases in the same way that network applications do
> via SOAP
> -	   over HTTP (deprecated starting with Release 6.0) or with WS-
> Management over
> -	   SOAP over HTTP. This means that some Intel AMT features can be
> accessed from a
> -	   local application using the same network interface as a remote
> application
> -	   communicating with Intel AMT over the network.
> -
> -	   When a local application sends a message addressed to the local Intel
> AMT host
> -	   name, the Intel LMS, which listens for traffic directed to the host
> name,
> -	   intercepts the message and routes it to the Intel MEI.
> -	   For more information:
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> -	   Under "About Intel AMT" => "Local Access"
> -
> -	   For downloading Intel LMS:
> -	   http://software.intel.com/en-us/articles/download-the-latest-intel-
> amt-open-source-drivers/
> -
> -	   The Intel LMS opens a connection using the Intel MEI driver to the
> Intel LMS
> -	   firmware feature using a defined UUID and then communicates with
> the feature
> -	   using a protocol called Intel AMT Port Forwarding Protocol (Intel APF
> protocol).
> -	   The protocol is used to maintain multiple sessions with Intel AMT
> from a
> -	   single application.
> -
> -	   See the protocol specification in the Intel AMT Software Development
> Kit (SDK)
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> -	   Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
> -	   => "Information for Intel(R) vPro(TM) Gateway Developers"
> -	   => "Description of the Intel AMT Port Forwarding (APF) Protocol"
> -
> -	2) Intel AMT Remote configuration using a Local Agent
> -
> -	   A Local Agent enables IT personnel to configure Intel AMT out-of-the-
> box
> -	   without requiring installing additional data to enable setup. The
> remote
> -	   configuration process may involve an ISV-developed remote
> configuration
> -	   agent that runs on the host.
> -	   For more information:
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> -	   Under "Setup and Configuration of Intel AMT" =>
> -	   "SDK Tools Supporting Setup and Configuration" =>
> -	   "Using the Local Agent Sample"
> -
> -	   An open source Intel AMT configuration utility,	implementing a local
> agent
> -	   that accesses the Intel MEI driver, can be found here:
> -	   http://software.intel.com/en-us/articles/download-the-latest-intel-
> amt-open-source-drivers/
> -
> -
> -Intel AMT OS Health Watchdog
> -============================
> -
> -The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
> -Whenever the OS hangs or crashes, Intel AMT will send an event -to any
> subscriber to this event. This mechanism means that -IT knows when a platform
> crashes even when there is a hard failure on the host.
> -
> -The Intel AMT Watchdog is composed of two parts:
> -	1) Firmware feature - receives the heartbeats
> -	   and sends an event when the heartbeats stop.
> -	2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
> -	   configures the watchdog and sends the heartbeats.
> -
> -The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
> -the Intel AMT Watchdog and to send heartbeats to it. The default timeout of
> the -watchdog is 120 seconds.
> -
> -If the Intel AMT is not enabled in the firmware then the watchdog client won't
> enumerate -on the me client bus and watchdog devices won't be exposed.
> -
> -
> -Supported Chipsets
> -==================
> -
> -7 Series Chipset Family
> -6 Series Chipset Family
> -5 Series Chipset Family
> -4 Series Chipset Family
> -Mobile 4 Series Chipset Family
> -ICH9
> -82946GZ/GL
> -82G35 Express
> -82Q963/Q965
> -82P965/G965
> -Mobile PM965/GM965
> -Mobile GME965/GLE960
> -82Q35 Express
> -82G33/G31/P35/P31 Express
> -82Q33 Express
> -82X38/X48 Express
> -
> ----
> -linux-mei@xxxxxxxxxxxxxxx
> --
> 2.17.1




[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux