Skip to content

Commit e5e6735

Browse files
bougoubougou
committed
chore: Improve documentation
1 parent 0a1dff4 commit e5e6735

File tree

2 files changed

+68
-67
lines changed

2 files changed

+68
-67
lines changed

‎CONTRIBUTING.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,44 +3,44 @@
33
Each command defined in the IPMI specification is a pair of request/response messages.
44
These IPMI commands are implemented as methods of the `ipmi.Client` struct in this library.
55

6-
`ipmitool` as example, some `ipmitool` cmdline are realized by calling just one underlying IPMI command,
7-
but many others are not. Like `ipmitool sdr list`, it's a loop of `GetSDR` IPMI command.
6+
Using `ipmitool` as an example, some `ipmitool` command lines are implemented by calling just one underlying IPMI command,
7+
while many others are not. For instance, `ipmitool sdr list` is a loop of `GetSDR` IPMI commands.
88

9-
So this library also implements some methods that are not IPMI commands defined
10-
in IPMI specification, but just some common helpers, like `GetSDRs` to get all SDRs.
9+
This library also implements some methods that are not IPMI commands defined
10+
in the IPMI specification, but rather common helpers, like `GetSDRs` to get all SDRs.
1111

1212
## IPMI Command Guideline
1313

14-
For a IPMI Command `DoSomething`:
14+
For an IPMI Command `DoSomething`:
1515

16-
- Must define `DoSomethingRequest` which conforms to the `ipmi.Request` interface, it holds the request message data.
17-
- Must define `DoSomethingResponse` which conforms to the `ipmi.Response` interface, it holds the response message data.
18-
- Must define `DoSomething` method on `ipmi.Client`
16+
- You must define `DoSomethingRequest` which conforms to the `ipmi.Request` interface; it holds the request message data.
17+
- You must define `DoSomethingResponse` which conforms to the `ipmi.Response` interface; it holds the response message data.
18+
- You must define the `DoSomething` method on `ipmi.Client`
1919

20-
For `DoSomething` method, you can pass `DoSomethingRequest` directly as the input parameter, like:
20+
For the `DoSomething` method, you can pass `DoSomethingRequest` directly as the input parameter, like:
2121

2222
```go
2323
func (c *Client) DoSomething(ctx context.Context, request *DoSomethingRequest) (response *DoSomethingResponse, err error) {
2424
response = &DoSomethingResponse{}
25-
err := c.Exchange(ctx,request, response)
25+
err = c.Exchange(ctx, request, response)
2626
return
2727
}
2828
```
2929

30-
or, you can pass some plain parameters, and construct the `DoSomethingRequest` in method body, like:
30+
or, you can pass plain parameters and construct the `DoSomethingRequest` in the method body, like:
3131

3232
```go
3333
func (c *Client) DoSomething(ctx context.Context, param1 string, param2 string) (response *DoSomethingResponse, err error) {
3434
request := &DoSomethingRequest{
3535
// construct by using input params
3636
}
3737
response = &DoSomethingResponse{}
38-
err := c.Exchange(ctx,request, response)
38+
err = c.Exchange(ctx, request, response)
3939
return
4040
}
4141
```
4242

43-
Calling `Exchange` method of `ipmi.Client` will fullfil all other complex underlying works.
43+
Calling the `Exchange` method of `ipmi.Client` will handle all other complex underlying work.
4444

4545
## ipmi.Request interface
4646

@@ -49,7 +49,7 @@ type Request interface {
4949
// Pack encodes the object to data bytes
5050
Pack() []byte
5151
// Command return the IPMI command info (NetFn/Cmd).
52-
// All IPMI specification specified commands are already predefined in this file.
52+
// All IPMI specification specified commands are already predefined in this repo.
5353
Command() Command
5454
}
5555

@@ -71,5 +71,5 @@ type Response interface {
7171

7272
## IPMI Command Response
7373

74-
- Define necessary fields per IPMI specification, but DO NOT define the completion code field in Response struct.
75-
- If there is no command-specific completion codes, just return an empty map for `CompletionCodes()` method.
74+
- Define necessary fields per IPMI specification, but DO NOT define the completion code field in the Response struct.
75+
- If there are no command-specific completion codes, just return an empty map for the `CompletionCodes()` method.

‎README.md‎

Lines changed: 52 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
# [go-ipmi](https://github.com/bougou/go-ipmi)
66

7-
[`go-ipmi`](https://github.com/bougou/go-ipmi) is a pure golang native IPMI library. It DOES NOT wraps `ipmitool`.
7+
[`go-ipmi`](https://github.com/bougou/go-ipmi) is a pure Golang native IPMI library. It DOES NOT wrap `ipmitool`.
88

99
## Usage
1010

@@ -21,28 +21,28 @@ func main() {
2121
password := "123456"
2222

2323
client, err := ipmi.NewClient(host, port, username, password)
24-
// Support local mode client if runs directly on linux
24+
// Supports local mode client when running directly on Linux
2525
// client, err := ipmi.NewOpenClient()
2626
if err != nil {
2727
panic(err)
2828
}
2929

30-
// you can optionally open debug switch
30+
// You can optionally enable debug mode
3131
// client.WithDebug(true)
3232

33-
// you can set interface type, enum range: open/lan/lanplus/tool, default open
33+
// You can set the interface type. Valid options are: open/lan/lanplus/tool (default: open)
3434
// client.WithInterface(ipmi.InterfaceLanplus)
3535

36-
// !!! Note !!!,
37-
// From v0.6.0, all IPMI command methods of the Client accept a context as the first argument.
36+
// !!! Note !!!
37+
// From v0.6.0, all IPMI command methods of the Client require a context as the first argument.
3838
ctx := context.Background()
3939

40-
// Connect will create an authenticated session for you.
40+
// Connect creates an authenticated session
4141
if err := client.Connect(ctx); err != nil {
4242
panic(err)
4343
}
4444

45-
// Now you can execute other IPMI commands that need authentication.
45+
// Now you can execute other IPMI commands that require authentication
4646

4747
res, err := client.GetDeviceID(ctx)
4848
if err != nil {
@@ -60,27 +60,27 @@ func main() {
6060

6161
## `goipmi` binary
6262

63-
The `goipmi` is a binary tool which provides the same command usages like `ipmitool`.
64-
The `goipmi` calls `go-ipmi` library underlying.
63+
The `goipmi` binary provides command usage similar to `ipmitool`.
64+
The `goipmi` tool uses the `go-ipmi` library under the hood.
6565

66-
The purpose of creating `goipmi` tool was not intended to substitute `ipmitool`.
67-
It was just used to verify the correctness of `go-ipmi` library.
66+
The purpose of creating the `goipmi` tool was not to substitute `ipmitool`.
67+
It was created to verify the correctness of the `go-ipmi` library.
6868

6969
## Functions Comparison with ipmitool
7070

71-
Each command defined in the IPMI specification is a pair of request/response messages.
71+
Each command defined in the IPMI specification consists of a pair of request/response messages.
7272
These IPMI commands are implemented as methods of the `ipmi.Client` struct in this library.
7373

74-
Some `ipmitool` cmdline usages are implemented by calling just one IPMI command,
75-
but others are not. Like `ipmitool sdr list`, it's a loop of `GetSDR` IPMI command.
74+
Some `ipmitool` command line operations are implemented by calling just one IPMI command,
75+
while others are not. For example, `ipmitool sdr list` involves a loop of `GetSDR` IPMI commands.
7676

77-
So this library also implements some methods that are not IPMI commands defined
78-
in IPMI specification, but just some common helpers, like `GetSDRs` to get all SDRs.
79-
These methods are marked with an asterisk (*) after the method name in the following docs.
77+
This library also implements some helper methods that are not IPMI commands defined
78+
in the IPMI specification, but are common utilities, like `GetSDRs` to get all SDRs.
79+
These methods are marked with an asterisk (*) after the method name in the following documentation.
8080

81-
The implementation logic of IPMI commands are almost same. See [Contributing](./CONTRIBUTING.md)
81+
The implementation logic of IPMI commands is largely consistent. See [Contributing](./CONTRIBUTING.md)
8282

83-
> More commands are ongoing ...
83+
> More commands are in development...
8484
8585
### IPM Device Global Commands
8686

@@ -97,13 +97,13 @@ The implementation logic of IPMI commands are almost same. See [Contributing](./
9797
| GetDeviceGUID | :white_check_mark: | |
9898
| GetNetFnSupport | :white_check_mark: | |
9999
| GetCommandSupport | :white_check_mark: | |
100-
| GetCommandSubfunctionSupport | | |
100+
| GetCommandSubfunctionSupport | :white_check_mark: | |
101101
| GetConfigurableCommands | :white_check_mark: | |
102-
| GetConfigurableCommandSubfunctions | | |
103-
| SetCommandEnables | | |
102+
| GetConfigurableCommandSubfunctions | :white_check_mark: | |
103+
| SetCommandEnables | :white_check_mark: | |
104104
| GetCommandEnables | :white_check_mark: | |
105-
| GetCommandSubfunctionsEnables | :white_check_mark: | |
106-
| GetSubfunctionsEnables | | |
105+
| SetCommandSubfunctionEnables | :white_check_mark: | |
106+
| GetCommandSubfunctionEnables | :white_check_mark: | |
107107
| GetOEMNetFnIanaSupport | | |
108108

109109
### BMC Watchdog Timer Commands
@@ -126,9 +126,10 @@ The implementation logic of IPMI commands are almost same. See [Contributing](./
126126
| GetMessage | :white_check_mark: | |
127127
| SendMessage | :white_check_mark: | |
128128
| ReadEventMessageBuffer | :white_check_mark: | |
129-
| GetBTInterfaceCapabilities | | |
129+
| GetBTInterfaceCapabilities | :white_check_mark: | |
130130
| GetSystemGUID | :white_check_mark: | mc guid |
131-
| SetSystemInfoParam | | |
131+
| SetSystemInfoParam | :white_check_mark: | |
132+
| SetSystemInfoParamFor (*) | :white_check_mark: | |
132133
| GetSystemInfoParam | :white_check_mark: | |
133134
| GetSystemInfoParamFor (*) | :white_check_mark: | |
134135
| GetSystemInfoParams (*) | :white_check_mark: | |
@@ -153,19 +154,19 @@ The implementation logic of IPMI commands are almost same. See [Contributing](./
153154
| GetUsername | :white_check_mark: |
154155
| SetUserPassword | :white_check_mark: | user set password |
155156
| TestUserPassword (*) | :white_check_mark: | user test |
156-
| ActivatePayload | | |
157-
| DeactivatePayload | | |
158-
| GetPayloadActivationStatus | | |
159-
| GetPayloadInstanceInfo | | |
160-
| SetUserPayloadAccess | | |
161-
| GetUserPayloadAccess | | sol payload status |
162-
| GetChannelPayloadSupport | | |
163-
| GetChannelPayloadVersion | | |
164-
| GetChannelOEMPayloadInfo | | |
165-
| MasterWriteRead | | |
157+
| ActivatePayload | :white_check_mark: | |
158+
| DeactivatePayload | :white_check_mark: | |
159+
| GetPayloadActivationStatus | :white_check_mark: | |
160+
| GetPayloadInstanceInfo | :white_check_mark: | |
161+
| SetUserPayloadAccess | :white_check_mark: | |
162+
| GetUserPayloadAccess | :white_check_mark: | sol payload status |
163+
| GetChannelPayloadSupport | :white_check_mark: | |
164+
| GetChannelPayloadVersion | :white_check_mark: | |
165+
| GetChannelOEMPayloadInfo | :white_check_mark: | |
166+
| MasterWriteRead | :white_check_mark: | |
166167
| GetChannelCipherSuites | :white_check_mark: | |
167-
| SuspendOrResumeEncryption | | |
168-
| SetChannelCipherSuites | | |
168+
| SuspendResumePayloadEncryption | :white_check_mark: | |
169+
| SetChannelSecurityKeys | :white_check_mark: | |
169170
| GetSystemInterfaceCapabilities | :white_check_mark: | |
170171

171172
### Chassis Device Commands
@@ -204,16 +205,16 @@ The implementation logic of IPMI commands are almost same. See [Contributing](./
204205
| Method | Status | corresponding ipmitool usage |
205206
| ------------------------- | ------------------ | ---------------------------- |
206207
| GetPEFCapabilities | :white_check_mark: | pef capabilities |
207-
| ArmPEFPostponeTimer | | |
208-
| SetPEFConfigParam | | |
209-
| GetPEFConfigParam | | |
210-
| GetPEFConfigParamFor (*) | | |
211-
| GetPEFConfigParams (*) | | |
212-
| GetPEFConfigParamsFor (*) | | |
213-
| SetLastProcessedEventId | | |
214-
| GetLastProcessedEventId | | |
215-
| AlertImmediate | | |
216-
| PEFAck | | |
208+
| ArmPEFPostponeTimer | :white_check_mark: | |
209+
| SetPEFConfigParam | :white_check_mark: | |
210+
| GetPEFConfigParam | :white_check_mark: | |
211+
| GetPEFConfigParamFor (*) | :white_check_mark: | |
212+
| GetPEFConfigParams (*) | :white_check_mark: | |
213+
| GetPEFConfigParamsFor (*) | :white_check_mark: | |
214+
| SetLastProcessedEventId | :white_check_mark: | |
215+
| GetLastProcessedEventId | :white_check_mark: | |
216+
| AlertImmediate | :white_check_mark: | |
217+
| PETAcknowledge | :white_check_mark: | |
217218

218219
### Sensor Device Commands
219220

@@ -227,9 +228,9 @@ The implementation logic of IPMI commands are almost same. See [Contributing](./
227228
| GetSensorHysteresis | :white_check_mark: | |
228229
| SetSensorThresholds | :white_check_mark: | |
229230
| GetSensorThresholds | :white_check_mark: | |
230-
| SetSensorEventEnable | | |
231+
| SetSensorEventEnable | :white_check_mark: | |
231232
| GetSensorEventEnable | :white_check_mark: | |
232-
| RearmSensorEvents | | |
233+
| RearmSensorEvents | :white_check_mark: | |
233234
| GetSensorEventStatus | :white_check_mark: | |
234235
| GetSensorReading | :white_check_mark: | |
235236
| SetSensorType | :white_check_mark: | |

0 commit comments

Comments
 (0)