xref: /openbmc/hiomapd/README.md (revision 22778044) 
1Copyright 2016 IBM
2
3Licensed under the Apache License, Version 2.0 (the "License");
4you may not use this file except in compliance with the License.
5You may obtain a copy of the License at
6
7  http://www.apache.org/licenses/LICENSE-2.0
8
9Unless required by applicable law or agreed to in writing, software
10distributed under the License is distributed on an "AS IS" BASIS,
11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12See the License for the specific language governing permissions and
13limitations under the License.
14
15# Intro
16The autotools of this requires the autotools-archive package for your
17system
18
19---
20
21Notes on messages:
22
23## Layout
24```
25Byte 0: COMMAND
26Byte 1: Sequence
27Byte 2-12: Data
28Byte 13: Response code
29Byte 14: Host controlled status reg
30Byte 15: BMC controlled status reg
31```
32## Commands
33```
34RESET_STATE
35GET_MBOX_INFO
36GET_FLASH_INFO
37READ_WINDOW
38CLOSE_WINDOW
39WRITE_WINDOW
40WRITE_DIRTY
41WRITE_FENCE
42COMPLETED_COMMANDS
43ACK
44```
45## Sequence
46Unique message sequence number
47
48## Responses
49```
50SUCCESS
51PARAM_ERROR
52WRITE_ERROR
53SYSTEM_ERROR
54TIMEOUT
55```
56
57## Information
58- Interrupts via control regs
59- Block size 4K
60- All multibyte messages are little endian
61
62### Commands in detail
63```
64	Command:
65		RESET_STATE
66	Data:
67		-
68	Response:
69		-
70
71	Command:
72		GET_MBOX_INFO
73	Data:
74		Data 0: API version
75	Response:
76		Data 0: API version
77		Data 1-2: read window size in blk size
78		Data 3-4: write window size in blk size
79
80	Command:
81		CLOSE_WINDOW
82		Data:
83			-
84		Response:
85			-
86	Command:
87		GET_FLASH_INFO
88		Data:
89			-
90		Response:
91			Data 0-3: Flash size
92			Data 4-7: Erase granule
93
94	Command:
95		READ_WINDOW
96		Data:
97			Data 0-1: Read window offset in blk size
98		Response:
99			Data 0-1: Read window pos in blk size
100
101	Command:
102		WRITE_WINDOW
103		Data:
104			Data 0-1: Write window offset in blk size
105		Response:
106			Data 0-1: Write window pos in blk size
107
108	Command:
109		WRITE_DIRTY
110		Data:
111			Data 0-1: Offset within window in blk size
112			Data 2-5: Number of dirty bytes
113		Response:
114			-
115
116	Command
117		WRITE_FENCE
118		Data:
119			Data 0-1: Offset within window in blk size
120			Data 2-5: Number of dirty bytes
121		Response:
122			-
123
124	Command:
125		ACK
126		Data:
127			Bits in the BMC reg to ack
128		Response:
129			*clears the bits*
130			-
131
132	Command:
133		COMPLETED_COMMANDS
134		Data:
135			-
136		Response:
137			Data 0: Number of seq numbers to follow
138			Data 1-N: Completed sequence numbers
139
140	BMC notifications:
141		If the BMC needs to tell the host something then it simply
142		writes to Byte 15. The host should have interrupts enabled
143		on that register, or otherwise be checking it regularly.
144		 - BMC reboot
145		 - Command complete
146		   The host should issue a command complete request to find
147		   out the sequence numbers to commands which have completed
148```
149