Re: [PATCH v7 2/2] Documentation: Add x86/amd_hsmp driver

["Chatradhi, Naveen Krishna" <nchatrad@amd.com>]

Hi

On 2/24/2022 8:50 PM, Hans de Goede wrote:
> [CAUTION: External Email]
>
> Hi,
>
> On 2/22/22 06:05, Naveen Krishna Chatradhi wrote:
>> This documentation for amd_hsmp driver explains how to use the
>> device interface.
>>
>> Signed-off-by: Naveen Krishna Chatradhi <nchatrad@amd.com>
>> Acked-by: Song Liu <song@kernel.org>
> This patch causes a number of new warning when running "make htmldocs":
>
> amd_hsmp.rst:51: WARNING: Literal block ends without a blank line; unexpected unindent.
> amd_hsmp.rst:68: WARNING: Literal block expected; none found.
> amd_hsmp.rst:69: WARNING: Inline emphasis start-string without end-string.
> amd_hsmp.rst:74: WARNING: Definition list ends without a blank line; unexpected unindent.
> amd_hsmp.rst: WARNING: document isn't included in any toctree
>
> I've fixed these before merging, but next time please run
> "make htmldocs" and check for new warnings before submitting
> documentation patches.
Sure, will do. Thank you for addressing them and accepting.
>
> Thank you for your patch, I've applied this patch to my review-hans
> branch:
> https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgit.kernel.org%2Fpub%2Fscm%2Flinux%2Fkernel%2Fgit%2Fpdx86%2Fplatform-drivers-x86.git%2Flog%2F%3Fh%3Dreview-hans&amp;data=04%7C01%7CNaveenKrishna.Chatradhi%40amd.com%7Cac8101d2dbed4f228b0208d9f7a938f5%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637813129193048361%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=KgolLZNNVoNynBa3nAt6agnb271BGHEev%2FXB0fKVIxc%3D&amp;reserved=0
>
> Note it will show up in my review-hans branch once I've pushed my
> local branch there, which might take a while.
>
> Once I've run some tests on this branch the patches there will be
> added to the platform-drivers-x86/for-next branch and eventually
> will be included in the pdx86 pull-request to Linus for the next
> merge-window.
>
> Regards,
>
> Hans
>
>
>
>
>> ---
>> Changes since v6:
>> Add acked by from Song Liu
>> Changes since v5:
>>   variable name changed from buf to args
>> Changes since v4:
>> struct hsmp_message is updated
>> Changes since v3:
>>   remove change ids
>> Changes since v2:
>>   Add statement saying the HSMP interface is supported only on
>>   server cpu models from AMD.
>> Changes since v1:
>>   None
>>
>>   Documentation/x86/amd_hsmp.rst | 85 ++++++++++++++++++++++++++++++++++
>>   1 file changed, 85 insertions(+)
>>   create mode 100644 Documentation/x86/amd_hsmp.rst
>>
>> diff --git a/Documentation/x86/amd_hsmp.rst b/Documentation/x86/amd_hsmp.rst
>> new file mode 100644
>> index 000000000000..9de7e028d6e3
>> --- /dev/null
>> +++ b/Documentation/x86/amd_hsmp.rst
>> @@ -0,0 +1,85 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +============================================
>> +AMD HSMP interface
>> +============================================
>> +
>> +Newer Fam19h EPYC server line of processors from AMD support system
>> +management functionality via HSMP (Host System Management Port).
>> +
>> +The Host System Management Port (HSMP) is an interface to provide
>> +OS-level software with access to system management functions via a
>> +set of mailbox registers.
>> +
>> +More details on the interface can be found in chapter
>> +"7 Host System Management Port (HSMP)" of the family/model PPR
>> +Eg: https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.amd.com%2Fsystem%2Ffiles%2FTechDocs%2F55898_B1_pub_0.50.zip&amp;data=04%7C01%7CNaveenKrishna.Chatradhi%40amd.com%7Cac8101d2dbed4f228b0208d9f7a938f5%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637813129193048361%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=751ukAhaHNuvoXtPZVr8ZBSIA7oWs3gdZijj72AXGVw%3D&amp;reserved=0
>> +
>> +HSMP interface is supported on EPYC server CPU models only.
>> +
>> +
>> +HSMP device
>> +============================================
>> +
>> +amd_hsmp driver under the drivers/platforms/x86/ creates miscdevice
>> +/dev/hsmp to let user space programs run hsmp mailbox commands.
>> +
>> +$ ls -al /dev/hsmp
>> +crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp
>> +
>> +Characteristics of the dev node:
>> + * Write mode is used for running set/configure commands
>> + * Read mode is used for running get/status monitor commands
>> +
>> +Access restrictions:
>> + * Only root user is allowed to open the file in write mode.
>> + * The file can be opened in read mode by all the users.
>> +
>> +In-kernel integration:
>> + * Other subsystems in the kernel can use the exported transport
>> +   function hsmp_send_message().
>> + * Locking across callers is taken care by the driver.
>> +
>> +
>> +An example
>> +==========
>> +
>> +To access hsmp device from a C program.
>> +First, you need to include the headers::
>> +
>> +  #include <linux/amd_hsmp.h>
>> +Which defines the supported messages/message IDs.
>> +
>> +Next thing, open the device file, as follows::
>> +
>> +  int file;
>> +
>> +  file = open("/dev/hsmp", O_RDWR);
>> +  if (file < 0) {
>> +    /* ERROR HANDLING; you can check errno to see what went wrong */
>> +    exit(1);
>> +  }
>> +
>> +The following IOCTL is defined:
>> +
>> +``ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)``
>> +  The argument is a pointer to a::
>> +
>> +struct hsmp_message {
>> +     __u32   msg_id;                         /* Message ID */
>> +     __u16   num_args;                       /* Number of input argument words in message */
>> +     __u16   response_sz;                    /* Number of expected output/response words */
>> +     __u32   args[HSMP_MAX_MSG_LEN];         /* argument/response buffer */
>> +     __u16   sock_ind;                       /* socket number */
>> +};
>> +
>> +The ioctl would return a non-zero on failure; you can read errno to see
>> +what happened. The transaction returns 0 on success.
>> +
>> +More details on the interface and message definitions can be found in chapter
>> +"7 Host System Management Port (HSMP)" of the respective family/model PPR
>> +eg: https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.amd.com%2Fsystem%2Ffiles%2FTechDocs%2F55898_B1_pub_0.50.zip&amp;data=04%7C01%7CNaveenKrishna.Chatradhi%40amd.com%7Cac8101d2dbed4f228b0208d9f7a938f5%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637813129193048361%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=751ukAhaHNuvoXtPZVr8ZBSIA7oWs3gdZijj72AXGVw%3D&amp;reserved=0
>> +
>> +User space C-APIs are made available by linking against the esmi library,
>> +which is provided by the E-SMS project https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdeveloper.amd.com%2Fe-sms%2F&amp;data=04%7C01%7CNaveenKrishna.Chatradhi%40amd.com%7Cac8101d2dbed4f228b0208d9f7a938f5%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637813129193048361%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=%2Fe%2BQAKkHf8VUGzxbJLsvnCtEm1UAhCOpepV6lLhtah4%3D&amp;reserved=0.
>> +See: https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Famd%2Fesmi_ib_library&amp;data=04%7C01%7CNaveenKrishna.Chatradhi%40amd.com%7Cac8101d2dbed4f228b0208d9f7a938f5%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C637813129193048361%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=LO1NdoruQ2SrBGrPeJcISwWYuegg42mDJPZu18len9o%3D&amp;reserved=0